borland Packages  Class Hierarchy  jbcl.dataset Package  Index 

PickListDescriptor class

java.lang.Object
   +----borland.jbcl.dataset.PickListDescriptor

About the PickListDescriptor class

Constructors  Properties  Methods  

Implements Serializable

The PickListDescriptor describes a pick list relationship between a Column of one DataSet, and a second DataSet that provides values from which you can choose. To access the PickListDescriptor in the JBuilder Inspector, select the pickList property of a Column component.

The DataSet that contains the items to display in the pick list is specified in the pickListDataSet property. The pickListDisplayColumns property describes the columns of that DataSet that are shown in the pick list.

Any control that follows the JBCL model-view architecture and is bound to a DataSet Column component that has its picklist property set, uses the PickListItemEditor as its itemEditor by default. JBCL model-view controls include:

Although the pickListDisplayColumns parameter is an array of String names of Column components to display, the PickListItemEditor can only display a single Column in the pick list. To display multiple columns in a pick list, set the itemEditor property of the Column to the PopupPickListItemEditor. The PopupPickListItemEditor is available from the JBCL tab of the Component Palette.

Once a row is selected, the values of the pickListColumns in the pickListDataset are copied into the destinationColumns of this DataSet.

Use the lookupDisplayColumn property to specify the name of the column in the pickListDataSet to display values from.

There are three basic ways to configure the pickList property, the first two being the more commonly used:

  1. A simple "fill in". For visual controls, the pickList editor provides a selection of values from a pickListDataSet. The selected values are filled into one or more column values.

    For this configuration, set the pickListDataSet, destinationColumns (columns to copy to), pickListColumns (columns to copy from the pickListDataSet), and pickListDisplayColumns (columns values to display from the pickListDataSet when the pickList column is being edited).

  2. "Fill in" and "lookup" display. Provides the same functionality as above, except you can specify a lookupDisplayColumn from the pickListDataSet. This allows you to store a "code number" code in the column, but display a "code description".

    The values from the lookupDisplayColumn in the pickListDataSet are displayed instead of the value that is stored in the pickList Column. The value to display is chosen by using the current values in destinationColumns to locate the row in the pickListDataSet that has the same values for its pickListColumns.

    If a match is found, the lookupDisplayColumn value for that row in the pickListDataSet is displayed. Note that the DataSet.setValue() and getValue() methods retrieve and set the "real" value stored. To retrieve the display value for such a column, use the DataSet.getDisplayVariant() method.

  3. Formal read only "lookup" display column. This configuration is a little more work to setup, but allows an application to show both the code and code description values. Although you can achieve a similar effect with the first configuration above, this configuration displays the code description from the pickListDataSet. So if the code description is changed in your pickListDataSet, that change will be refleted in your DataSet since this display value is always "looked up". In the first configuration described above, if the code description changes in the pickListDataSet, your DataSet will still show the old "fill in" values.

    The lookup column is a special calc column that retrieves its display values from the pickListDataSet. Although the pickList editor is activated when edits are attempted on this column, no value can be set on this column. It always retrieves its values by looking them up in the pickListDataSet. The lookup operation uses the same mechanism and properties described in the second configuration above. To create a lookup Column, you must add a Column to your DataSet and set its calcType property to CalcType.LOOKUP. Set up the pickList property much like configuration #2. The only difference is that the lookup column cannot be one of the columns listed in the destinationColumns property.

For more information on pick lists, see the pickList property of the Column component. For examples of pick lists in an application, see Looking up choices with a pick list in the Database Application Developer's Guide.


PickListDescriptor constructors

PickListDescriptor properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in java.lang.Object

PickListDescriptor methods

Methods implemented in java.lang.Object


PickListDescriptor constructors

PickListDescriptor(borland.jbcl.dataset.DataSet, java.lang.String[], java.lang.String[], java.lang.String[], boolean)

  public PickListDescriptor(borland.jbcl.dataset.DataSet pickListDataSet, java.lang.String[] pickListColumns, java.lang.String[] pickListDisplayColumns, java.lang.String[] destinationColumns, boolean enforceIntegrity)
Constructs a PickListDescriptor object with the properties stated in its parameters.

Parameters:

pickListDataSet
The DataSet object that contains the data for display in the pick list.
pickListColumns
The columns of the pickListDataSet from which values in the selected row are copied to the destinationColumns.
pickListDisplayColumns
The Column components of the DataSet to display in the pick list. This property is expressed as an array of String names.
destinationColumns
The Column components that are populated with the values associated with the selected pick list choice. This property is expressed as an array of String column names.
enforceIntegrity
Whether to enforce data integrity rules (data constraints) on the data added to the destinationColumns.

PickListDescriptor(borland.jbcl.dataset.DataSet, java.lang.String[], java.lang.String[], java.lang.String[], java.lang.String, boolean)

  public PickListDescriptor(borland.jbcl.dataset.DataSet pickListDataSet, java.lang.String[] pickListColumns, java.lang.String[] pickListDisplayColumns, java.lang.String[] destinationColumns, java.lang.String lookupDisplayColumn, boolean enforceIntegrity)
Constructs a PickListDescriptor object with the properties stated in its parameters.

Parameters:

pickListDataSet
The DataSet object that contains the data for display in the pick list.
pickListColumns
The columns of the pickListDataSet from which values in the selected row are copied to the destinationColumns.
pickListDisplayColumns
The Column components of the DataSet to display in the pick list. This property is expressed as an array of String names.
destinationColumns
The Column components that are populated with the values associated with the selected pick list choice. This property is expressed as an array of String column names.
lookupDisplayColumn
The name of the Column in the picklistDataSet to display in this column.
enforceIntegrity
Whether to enforce data integrity rules (data constraints) on the data added to the destinationColumns.

PickListDescriptor properties

destinationColumns

 public final String[] getDestinationColumns()
Read-only property that returns the String names of the Column components that are filled in when an entry in the pick list is selected. Set this property using the PickListDescriptor constructor.

enforceIntegrity

 public boolean isEnforceIntegrity()
Read-only property that returns whether to enforce data integrity rules (data constraints) on the data added to the destinationColumns. Set this property using the PickListDescriptor constructor.

lookupDisplayColumn

 public final String getLookupDisplayColumn()
Read-only property that returns the name of the Column in the picklistDataSet to display in data-aware controls for this column.

This property was added in JBuilder 2.0.

pickListColumns

 public final String[] getPickListColumns()
Read-only property that returns the Column components to read from when filling in data from the pickListDataSet into the columns specified in the destinationColumns property. Set this property using the PickListDescriptor constructor.

pickListDataSet

 public final DataSet getPickListDataSet()
Read-only property that returns the pickListDataSet used to choose values from. Set this property using the PickListDescriptor constructor.

pickListDisplayColumns

 public final String[] getPickListDisplayColumns()
Read-only property that reuturns a String array of the Column names to display from the pickListDataSet. Set this property using the PickListDescriptor constructor.