Skip to main content
Jump to: navigation, search


Wiki Home

Value field to propose multiple choices (hierarchical).

  • implements: I obj.pngITreeBox<T>
  • extends: C obj.pngAbstractTreeBox<T>


Add a description

  • Value is stored in a Array: T[]
    It cointains the keys, whose entries were checked by the user. If no entry was checked, the value will be null.
  • Like a Smart field but for multiple Values. Differ from a ListBox because it is hierarchical.
  • Use a CodeType or a LookupCall


RAP SWT Swing Swing Rayo
Scout 3.8 TreeBox RAP.png Scout 3.8 TreeBox SWT.png Scout 3.8 TreeBox Swing.png Scout 3.8 TreeBox Swing Rayo.png


Defined with getConfiguredXxxxxx() methods.

See also the Field and the Value field pages for the properties that all fields have in common.


The fields of a TreeBox are populated through the use of a LookupCall:

protected Class<? extends LookupCall> getConfiguredLookupCall() {
  return MyLookupCall.class;

That lookup call in turn uses a lookup service:

public class MyLookupCall extends LookupCall{
  private static final long serialVersionUID = 1L;
  protected Class<? extends ILookupService> getConfiguredService() {
    return IMyLookupService.class;

The lookup service on the server uses an SQL query to return the content for those fields (see below).


By default the TreeBoxField shows a collapsed tree if not all elements of the tree can be shown in the field at the current size. This can be changed to always expand the tree by setting the AutoExpandAll property to true

protected boolean getConfiguredAutoExpandAll() {
  return true;


Defined with execXxxxxx() methods.

See also the Field and the Value field pages for the events that all fields have in common.


By default the entries in the list and tree are sorted by the text attribute (i.e. the visible text), not the key. This can be changed by defining a filtering function:

protected void execFilterLookupResult(LookupCall call, List<LookupRow> result) throws ProcessingException {
  java.util.Collections.sort(result, new MyLookupRowComparator());

This filter function requires a comparator class which implements Comparator<LookupRow>:

public class MyRowComparator implements Comparator<LookupRow> {
  public int compare(LookupRow object1, LookupRow object2) {
    if (object1 == null) return -1;
    if (object2 == null) return 1;
    // sort on 'text' (default behaviour)
    //return object1.getText().compareTo(object2.getText());
    // sort on 'key'
    return ((Long) object1.getKey()).compareTo((Long) object2.getKey());


Review needed
This section needs a review: There are 2 pages that mentioned LookupService:
  • Lookup Service (lookup service that is not specific)
  • Sql Lookup Service (convenience lookup service, ready to use a database (eg providing getConfiguredSqlSelect()))
In my opinion the content of this section needs to be merged to one of these 2 pages (probably the second one).

The MiniCRM tutorial describes how to use a lookup service to populate SmartFields (e.g. dropdown boxes).

Populating TreeBoxFields and ListBoxFields require more fields to be returned.

The LookupService has a getConfiguredSqlSelect() method which returns a number of fields. The first two attributes (key and text) are compulsory, any of the other attributes are optional (and can be skipped by returning null or an empty string; if all remaining fields would be skipped, the query can just end early). The attributes are returned in the following order:

protected String getConfiguredSqlSelect() {
  return "" +
      "SELECT " +
      "   C.COMPANY_NR, " +                     // key
      "   C.SHORT_NAME || ': ' || C.NAME, " +   // text
      "   C.LOGO, " +                           // iconId
      "   C.TOOLTIP, " +                        // tooltip
      "   'F0F0F0', " +                         // background
      "   '404040', " +                         // foreground
      "   '" + Font.SERIF + "', " +             // font: not yet clear how this works
      "   1, "+                                 // enabled
      "   null, "+                              // parent
      "   1 "+                                  // active 
      "FROM COMPANY C " +
      "WHERE 1=1 " +
      "AND (C.TYPE_UID =&nbsp;:master OR&nbsp;:master IS NULL) " +
      "     AND C.COMPANY_NR =&nbsp;:key  " +
      "     AND ((UPPER(C.NAME) LIKE '%'|| UPPER(:text)||'%') OR (UPPER(C.SHORT_NAME) LIKE '%'||UPPER(:text)||'%')) " +
      "      ";

In principle a LookupService can be used for SmartFields, TreeBoxFields and ListBoxFields, however not all attributes are used for all fields (and behaviour between Swing and SWT differs for some of them).

The attributes have the following functions:

  • key
    This is the value which will be returned in the array T[]
  • text
    This is the text being displayed
  • iconId
    This is an icon id that needs to be resolvable using an IconProviderService/IconLocator. With TreeBoxFields and ListBoxFields the icon will only be shown for Swing but not SWT
  • tooltip
    The tooltip text will be shown when hovering over the entry with the mouse.
  • background
    The background colour used for this entry ("RRGGBB" in hex)
  • foreground
    The foreground colour used for this entry ("RRGGBB" in hex)
  • font
    The font to be used (TODO: needs more information on how to use this)
  • enabled
    TODO: needs more information on the difference between enabled and active
  • parent
    A reference to the key attribute of another entry and is used to build the hierarchy of elements
  • active
    TODO: needs more information on the difference between enabled and active
Update description for font, enabled and active

See Also

Back to the top