Multi-Selection Capable TList Information

The MultiSelect Pluggable Java Component (PJC) provides an implementation of a normal Forms list item of subtype TList with one additional capability, the ability to select multiple entries in the list simultaneously.  The enhanced list supports all of the standard selection gestures such as Shift-Click for contiguous selection and Control-Click for selecting individual elements

The demo form shows how two such enhanced TLists together can be used to create a fully functional shuttle control.

Modules In This Demo

The MultiSelect demo consists of the following files (relative directories shown in brackets):

  1. multiselectl.fmb/fmx [forms]- The demo form
  2. MultiSelectTList.java [src/oracle/forms/demos/enhancedItems] - source code for the PJC class
  3. multiselect.jar [classes]- the compiled and jarred java class.

The doc directory and the classes directory contain the JavaDoc for the code and the compiled classes respectively

Reusing the code

Setting up Forms Services

In order for an application to be able to use the MultiSelect PJC the relevant configuration in the formsweb.cfg file has to ensure that the supplied multiselect.jar (or another jar file containing the compiled MultiSelectTlist.class) is included in the relevant archive setting.

An entry in the formsweb.cfg file for an application that used the MultiSelect TList  would look like this:

[MultiSelect]
pageTitle=OracleAS Forms Services - MultiSelect Demo
IE=jinitiator
baseHTMLJInitiator=demobasejini.html
archive_jini=frmall_jinit.jar,multiselect.jar
form=multiselectforms/java
width=675
height=480
separateFrame=false
splashScreen=no
lookAndFeel=oracle
colorScheme=blue
background=/formsdemo/images/blue.gif

Using the PJC in your Form

To use the MultiSelect TList PJC you must first create a normal Forms list item and set the List Style property to Tlist

Then set the Implementation Class property for this list item to oracle.forms.demos.enhancedItems.MultiSelectTList.  Note that this property is case sensitive and must be entered exactly as shown.

Enabling and Using the Multi-Select capabilities of the PJC

By default the enhanced TList continues to operate just like a normal TList, in order to enable the multi-select capability you must set a custom property on the item ENABLE_LIST_MULTISELECT to the string value 'true' e.g.

 SET_CUSTOM_PROPERTY('PJC.MULTISELECT_LIST',1,'ENABLE_LIST_MULTISELECT','true');

The first argument to Set_Custom_Property() is the name or id of the PJC enabled item.  The second parameter defines the instance of the control that you wish to set the property on.  This index number is one based and represents the physical control in the user interface (rather than the record number in the underlying block). You can use the constant ALL_ROWS to set the property on all instances of the PJC for this field.  The third argument is the custom property that is being set on the PJC and the forth the value.

Once multi-select is enabled on the list item, the normal value of the field no longer reflects the selection in the control, as the 'value' (as referenced by :block.field) can only represent one value, rather than multiple values.  When using the MultiSelect TList PJC in multi-select mode, the value of the field is undefined.  To obtain the list of selected entries in the PJC you must instead use the custom property LIST_SELECTION using Get_Custom_Property(). e.g.

 selection := GET_CUSTOM_PROPERTY('PJC.MULTISELECT_LIST',1,'LIST_SELECTION');

The value returned from Get_Custom_Property() will be a comma delimited string containing the index numbers (one based) of the selected elements in the list.

To select a set of values on the list use Set_Custom_Property() with the same LIST_SELECTION property, supplying a comma delimited list of index numbers for the selection.  Any previous selection will be replaced with these new selections.

To clear the selections on the list item simply set the custom property CLEAR_LIST_SELECTION to the value 'true'

Apart from the multi-select capabilities, the control rendered by this PJC is a normal Forms TList control.  It can be populated from a record group or statically, and all the normal List Item built-ins can be used against it.

Custom Property Summary

Property Get Set Valid Values / Return Value Purpose
ENABLE_LIST_MULTISELECT No Yes 'true' | 'false' Switches the TList in and out of multi-select mode
LIST_SELECTION Yes Yes Comma delimited string of index numbers Get or set the list of selected element numbers
CLEAR_LIST_SELECTION No Yes 'true' Clears the current selection
DEBUGMESSAGES No Yes 'true' | 'false' Enables/disables debugging to the Java Console for this instance of the control.