Scout/Concepts/TreeBox

Scout

Wiki Home

Website

Download • Git

Community

Forums • Blog • Twitter • G+

Bugzilla

Bugzilla

Value field to propose multiple choices (hierarchical).

• implements: ITreeBox<T>
• extends: AbstractTreeBox<T>

Description

TODO
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

Screenshot

RAP	SWT	Swing	Swing Rayo

Properties

Defined with getConfiguredXxxxxx() methods.

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

getConfiguredLookupCall()

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

@Override
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;
  @Override
  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).

getConfiguredAutoExpandAll()

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

@Override
protected boolean getConfiguredAutoExpandAll() {
  return true;
}

Events

Defined with execXxxxxx() methods.

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

execFilterLookupResult()

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:

@Override
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> {
  @Override
  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());
  }
}

LookupService

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:

@Override
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 = :master OR :master IS NULL) " +
      "     AND C.COMPANY_NR = :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
  

TODO
Update description for font, enabled and active

See Also

• Smart field
• Value field
• Field
• Form