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

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

public class FormulaFieldController
extends java.lang.Object

This object is used to add, remove, and modify report formulas. Report formulas act upon reports and not on records, groups, or other data definition types. For information on handling record and group selection formulas, see the Filter object.

Note that any fields you want displayed in your report must be added to the ResultFields array. For more information, see the ResultFieldController object.

Tip: To access the FormulaFieldController, use the getFormulaFieldController method in the DataDefController object.


Method Summary
 int add(IFormulaField formulaField)
           Adds a formula field to the report.
 int add(java.lang.String formulaName, java.lang.String formulaText, FormulaSyntax formulaSyntax)
           Adds a formula field to the report.
 boolean canSupportSyntax(FormulaSyntax eSyntax)
           Returns true if the type of syntax used to write the formula is supported, and false otherwise.
 java.lang.String check(IFormulaField spFormulaField)
           Returns an empty string if the formula is valid, and an error message explaining why the formula is not valid otherwise.
 void modify(IFormulaField oldFormulaField, IFormulaField newFormulaField)
           Modifies a formula in a report.
 void modify(int nIndex, IFormulaField newFormulaField)
           Modifies a formula in a report.
 void remove(IFormulaField formulaField)
           Removes a formula from the report.
 void remove(int index)
           Removes a formula from the report.
 void remove(java.lang.String formulaName)
           Removes a formula 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(IFormulaField formulaField)
        throws ReportSDKException

Adds a formula field to the report. This method returns the index of the item after it has been added to the FormulaFields collection. The collection of FormulaField objects can be accessed by using the getFormulaFields() method in the DataDefinition object. The index is zero-based.

Before adding a formula field to the report, use the check method to see if the formula is valid.

Note: Any fields that you want displayed in your report must be added to the ResultFields array. For more information, see ResultFieldController object.

Parameters:
formulaField - The formula field that you want to add. This formula field must have a unique name. If the field value type is unknown, the controller will parse the formula text. If the formula is valid, then the field information--including the field value type, value length, and options--will be updated. If the syntax is invalid, an exception will be thrown.
Returns:
An int that specifies the index of the item added.
Throws:
ReportSDKException

canSupportSyntax

public boolean canSupportSyntax(FormulaSyntax eSyntax)

Returns true if the type of syntax used to write the formula is supported, and false otherwise.

Parameters:
eSyntax - The formula syntax type.
Returns:
true if the type of syntax used to write the formula is supported, and false otherwise.

check

public java.lang.String check(IFormulaField spFormulaField)
                       throws ReportSDKException

Returns an empty string if the formula is valid, and an error message explaining why the formula is not valid otherwise.

Parameters:
spFormulaField - The formula that you want checked.
Returns:
A null String ("") if the formula is valid or an error message if the formula is not valid.
Throws:
ReportSDKException

modify

public void modify(int nIndex,
                   IFormulaField newFormulaField)
            throws ReportSDKException

Modifies a formula in a report. The collection of FormulaField objects can be accessed by using the getFormulaFields() method in the DataDefinition object. The index is zero-based.

Parameters:
nIndex - The index of the formula to be modified in the FormulaFields collection.
newFormulaField - The newly modified FormulaField object. The changes are applied to the copy of the field in the DataDefinition object. The old field name and the new field name are the same. If the field value type is unknown, the controller will parse the formula text. If the formula is valid, then the field information--including the field value type, value length, and options--will be updated.
Throws:
ReportSDKException

modify

public void modify(IFormulaField oldFormulaField,
                   IFormulaField newFormulaField)
            throws ReportSDKException

Modifies a formula in a report. The collection of FormulaField objects can be accessed by using the getFormulaFields() method in the DataDefinition object. The index is zero-based.

Parameters:
oldFormulaField - The FormulaField object to be modified in the FormulaFields collection.
newFormulaField - The newly modified FormulaField object. The changes are applied to the copy of the field in the DataDefinition object. The old field name and the new field name are the same. If the field value type is unknown, the controller will parse the formula text. If the formula is valid, then the field information--including the field value type, value length, and options--will be updated.
Throws:
ReportSDKException

remove

public void remove(int index)
            throws ReportSDKException

Removes a formula from the report. The collection of FormulaField objects can be accessed by using the getFormulaFields() method in the DataDefinition object. The index is zero-based.

Parameters:
index - The index of the formula to be removed from the FormulaFields collection.
Throws:
ReportSDKException

remove

public void remove(IFormulaField formulaField)
            throws ReportSDKException

Removes a formula from the report. The collection of FormulaField objects can be accessed by using the getFormulaFields() method in the DataDefinition object. The index is zero-based.

Parameters:
formulaField - The FormulaField object to be removed from the FormulaFields collection.
Throws:
ReportSDKException

add

public int add(java.lang.String formulaName,
               java.lang.String formulaText,
               FormulaSyntax formulaSyntax)
        throws ReportSDKException

Adds a formula field to the report. This method returns the index of the item after it has been added to the Fields collection. It will return a value of -1 if it fails. The collection of FormulaField objects can be accessed by using the FormulaFields property in the DataDefinition object. This object should always be accessed through its controller, the DataDefController object. The index is zero-based.

Any fields that you want displayed in your report must be added to the ResultFields array. For more information, see ResultFieldController Object.

Example:

"This sample shows how to add a formula field to a Crystal report. Formula fields allow you to put data on the report that may not exist in any of the data fields.For example, to calculate the number days it takes to process each order, you need a formula that determines the number of days between the order date and the ship date. These formulas are added to the FormulaFields collection, which can be modified by using the DataDefController. For more information about formula fields, see the Crystal Reports Online Help."

 DataDefController dataDefController = clientDoc.getDataDefController();
 FormulaFieldController formulaFieldController = dataDefController.getFormulaFieldController();
 int ret = formulaFieldController.add("newFormula", "Date(1999, 12, 31)", FormulaSyntax.crystal);
 

Parameters:
formulaName - the name of the formula field that you want to add. The formula name must be in the short name format as defined by FieldDisplayNameType. If the report already has a formula with this name, a fieldAlreadyExists exception will be thrown.
formulaText - - the formula string you want to add. The controller will parse the formula text. If the syntax of the formula is correct when validated against formulaSyntax, a new formula will be added to the report. If the syntax of the formula is incorrect, a invalidFormulaField exception will be thrown.
formulaSyntax - - the formula syntax used to validate the formulaText. The formula syntax is defined by FormulaSyntax.
Returns:
int the index of the item after it has been added to the report
Throws:
ReportSDKException

remove

public void remove(java.lang.String formulaName)
            throws ReportSDKException

Removes a formula from the report. The collection of FormulaField objects can be accessed by using the getFormulaFields() method in the DataDefinition object. The index is zero-based.

Example:

This sample shows how to remove a formula field from a Crystal report. Formulas used by a Crystal report are stored in the FormulasFields collection and can be accessed through the FormulaFieldController.

 DataDefController dataDefController = clientDoc.getDataDefController();
 FormulaFieldController formulaFieldController = dataDefController.getFormulaFieldController();
 formulaFieldController.remove( "newFormula" );
 

Parameters:
formulaName - the name of the formula to be removed from the FormulaFields collection.
Throws:
ReportSDKException