com.crystaldecisions.sdk.occa.report.application
Class ResultFieldController

java.lang.Object
  extended by com.crystaldecisions.sdk.occa.report.application.ResultFieldController

public class ResultFieldController
extends java.lang.Object

This object is used to add, remove, and move result fields in a report. Results fields are fields that are used in the report--for example, database fields, parameter fields, and formula fields. You must add any fields that you want to appear on the report to the collection of ResultField objects. This means that the ResultFields collection will consist of many different types of fields.

Note: ResultField objects are practically implemented by Field objects.

When a field is added to the ResultFields collection, a corresponding FieldObject object is added to the report's Details section. Many field objects can reference the same result field. If all the field objects that use a particular result field are removed, then the result field will also be removed.

Use the appropriate controller to validate or modify fields before adding them to the ResultFields collection. Summary fields are an exception to this rule; if a summary field is added to (or removed from) the collection of SummaryField objects, then it is automatically added to (or removed from) the collection of ResultField objects.

Tip: To access the ResultFieldController, use the getResultFieldController method in the DataDefController object.


Method Summary
 void add(Fields fields)
           Adds a fields collection to the report.
 int add(int indexToAdd, IField field)
           Adds a result field to the report.
 void move(IField field, int indexToMoveTo)
           Moves a result field from one position in the report to another.
 void move(int nFrom, int nTo)
           Moves a result field from one position in the report to another.
 void remove(IField field)
           Removes a result field from the report.
 void remove(int index)
           Removes a result field from the report.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

add

public int add(int indexToAdd,
               IField field)
        throws ReportSDKException

Adds a result field to the report. This method returns the index of the item in the collection after it has been added. The collection of ResultField objects can be accessed through the getResultFields method in the DataDefinition object. The index is zero-based. Summary fields that are added to the ResultFields collection are automatically added to the SummaryFields collection; summary fields that are added to their own collection are also added to ResultFields.

Once a field has been added to the collection of ResultFields with the ResultFieldController, if it is modified within its own collection, it is also modified in ResultFields. For example, if you modify a ParameterField in ResultFields, it is automatically modified in its own ParameterFields collection.

Parameters:
indexToAdd - The position in the ResultFields collection where you want to add the Field object. Specify -1 to add the object to the end of the array.
field - The Field object that you want to add to the report.
Returns:
An int that specifies the index at which the Field object was added.
Throws:
ReportSDKException

move

public void move(int nFrom,
                 int nTo)
          throws ReportSDKException

Moves a result field from one position in the report to another. The collection of ResultField objects can be accessed by using the getResultsFields method in the DataDefinition object. The index is zero-based. When a result field is moved, the position of the fields in the rowset changes. However, changing the order of the result fields will not move field objects in the details sections of the report (for example, database fields and formula fields) unless a report template is applied. Applying a report template automatically formats the report, ensuring that the fields in the report's details section are in the same order as in the ResultFields collection.

For instance, if you have two database fields--Field A and Field B--in the ResultFields array and you swap their positions but do not apply a report template, then nothing will happen. However, if you do apply a report template, the details will change positions on the report, along with any corresponding summary fields.

Parameters:
nFrom - The index of the Field object to be moved in ResultFields.
nTo - The new index position of the Field object.
Throws:
ReportSDKException

move

public void move(IField field,
                 int indexToMoveTo)
          throws ReportSDKException

Moves a result field from one position in the report to another. The collection of ResultField objects can be accessed by using the getResultsFields method in the DataDefinition object. The index is zero-based. When a result field is moved, the position of the fields in the rowset changes. However, changing the order of the result fields will not move field objects in the details sections of the report (for example, database fields and formula fields) unless a report template is applied. Applying a report template automatically formats the report, ensuring that the fields in the report's details section are in the same order as in the ResultFields collection.

For instance, if you have two database fields--Field A and Field B--in the ResultFields array and you swap their positions but do not apply a report template, then nothing will happen. However, if you do apply a report template, the details will change positions on the report, along with any corresponding summary fields.

Parameters:
field - The Field object to be moved in ResultFields.
indexToMoveTo - The new index position of the Field object.
Throws:
ReportSDKException

remove

public void remove(int index)
            throws ReportSDKException

Removes a result field from the report. The collection of ResultField objects can be accessed by using the getResultsFields method in the DataDefinition object. The index is zero-based. Removing a parameter field, formula field, or database field from the ResultFields collection does not remove it from its own collection. This means that even if a field does not appear on the report, it will remain part of the report's definition, and you can choose to add it to the report later. However, if a field is removed from its own collection, it is removed from ResultFields.

Parameters:
index - The index of the Field object to be removed from the ResultFields collection.
Throws:
ReportSDKException

remove

public void remove(IField field)
            throws ReportSDKException

Removes a result field from the report. The collection of ResultField objects can be accessed by using the getResultsFields method in the DataDefinition object. The index is zero-based. Removing a parameter field, formula field, or database field from the ResultFields collection does not remove it from its own collection. This means that even if a field does not appear on the report, it will remain part of the report's definition, and you can choose to add it to the report later. However, if a field is removed from its own collection, it is removed from ResultFields.

Parameters:
field - The Field object to be removed from the ResultFields collection.
Throws:
ReportSDKException

add

public void add(Fields fields)
         throws ReportSDKException

Adds a fields collection to the report.

Example:

This sample shows how to add a result field to the Details section of a report. Results fields are fields that are used in the report, such as database fields, parameter fields and formula fields. Any fields that you want to appear on the report must be added to the collection of ResultFields. When a field is added to the ResultFields collection, a corresponding FieldObject object is added to the report's Details section.

 DataDefController dataDefController = clientDoc.getDataDefController();
 ResultFieldController resultFieldController = dataDefController.getResultFieldController();
 resultFieldController.add(fields);
 

Parameters:
fields - the Fields object to add to the report
Throws:
ReportSDKException