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

java.lang.Object
  |
  +--com.crystaldecisions.sdk.occa.report.application.FilterController

public class FilterController

extends java.lang.Object

This object is used to modify filters in a report. Filters are used in record selection and group selection formulas. A filter can be a complex formula string that is stored in the getFreeEditingText method in the IFilter object, or a simple formula string that is parsed into an array of FilterItems. FilterItems are stored in the same order they appear in the formula string.

If you add a filter that has an invalid syntax, the method that you are using will not fail; instead, an error is returned when you try to view the report.

Tip: To access the FilterController object, use the DataDefController.getGroupFilterController() method or the DataDefController.getRecordFilterController() property in the DataDefController object.

Method Summary

int	addItem(int index, IFilterItem filterItem) Adds a FilterItem object to an array of FilterItems in the Filter object.
boolean	canFilterOn(IField field) Returns true if the field can be filtered, and false otherwise.
java.lang.String	getFormulaText() Returns the filter formula text for a particular record or group filter If there are FilterItem objects (either FieldRangeFilterItem objects or OperatorFilterItem objects) stored in the FilterItems collection, a string representation of the filter is returned.
void	modify(IFilter filter) Modifies the filter for a particular record or group selection.
void	modifyItem(int index, IFilterItem newItem) Modifies a FilterItem in an array of FilterItems in the Filter object.
void	moveItem(int moveFrom, int moveTo) Moves a FilterItem object in an array of FilterItems in the Filter object.
int	removeItem(int index) Removes a FilterItem object from an array of FilterItems in the Filter object.
int	removeItemEx(int index, boolean repair) Removes a FilterItem object from an array of FilterItems in the Filter object.
void	setFormulaText(java.lang.String text) Modifies the filter formula text for a particular record or group filter.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addItem

public int addItem(int index,
                   IFilterItem filterItem)
            throws ReportSDKException

Adds a FilterItem object to an array of FilterItems in the Filter object. The index is zero-based.

This method adds a single filter item to the collection, and returns the index of the item in the collection. If you want to replace the entire filter with a modified one, use the modify method.

The FilterItem object is used as a base from which the FieldRangeFilterItem and OperatorFilterItem inherit. When you add a FieldRangeItem to the FilterItems collection, you are adding one of these two objects.

Parameters:

index - The position in the array where you want to add the FilterItem object. Specify -1 to add the object to the end of the array.

filterItem - The FilterItem that you want to add.

Returns:

An int that specifies the position of the item after it has been added.

Throws:

ReportSDKException

canFilterOn

public boolean canFilterOn(IField field)

Returns true if the field can be filtered, and false otherwise.

Use this method to determine if a field can be added to a record filter or a group filter. For example, a recurring field, formula field, or parameter field can be added to a record filter, whereas a summary field can be added only to a group filter. Only summary fields and formula fields can be used to filter groups.

Parameters:

field - The field whose data is being filtered.

Returns:

Returns true if the field can be filtered, and false otherwise.

modify

public void modify(IFilter filter)
            throws ReportSDKException

Modifies the filter for a particular record or group selection. When modifying a filter you have two options:

• You can modify the FreeEditingText property.
• You can modify the FilterItems property.

If you modify the FreeEditing text, you are adding a custom selection formula that cannot be parsed. For example, you might add a formula with an "If...Then...Else" structure.

If you modify the FilterItems property, you are adding a whole filter. You can either clone the Filter object using its clone method, modify the clone, and then pass this to the modify method as the filter parameter, or you can replace an existing filter with an entirely new one. If you want to modify a single item in an array of FilterItems, use the modifyItem method.

Parameters:

filter - The newly modified filter. This filter can be a FreeEditingText filter or a whole filter consisting of IFilterItem objects.

Throws:

ReportSDKException

modifyItem

public void modifyItem(int index,
                       IFilterItem newItem)
                throws ReportSDKException

Modifies a FilterItem in an array of FilterItems in the Filter object. The index is zero-based.

This method modifies a single filter item in the collection. If you want to replace the entire filter with a modified one, use the modify method.

Parameters:

index - The index of the FilterItem object to be modified.

newItem - The new FilterItem object. The FilterItem object is used as a base from which the FieldRangeFilterItem object and OperatorFilterItem object inherit. When you add a FieldRangeItem to the FilterItems collection, you are adding one of these two objects.

Throws:

ReportSDKException

moveItem

public void moveItem(int moveFrom,
                     int moveTo)
              throws ReportSDKException

Moves a FilterItem object in an array of FilterItems in the Filter object. The index is zero-based.

This method moves a single filter item from one position in the array to another. If you want to replace the entire filter with a modified one, use the modify method. Note, changing the position of the objects in the array alters the functionality of the formula.

Parameters:

moveFrom - The index of the FilterItem object to be moved.

moveTo - The new index position of the FilterItem object.

Throws:

ReportSDKException

removeItem

public int removeItem(int index)
               throws ReportSDKException

Removes a FilterItem object from an array of FilterItems in the Filter object. The index is zero-based.

This method removes a single filter item from the array. If you want to replace the entire filter with a modified one, use the modify method.

Once a filter item has been removed, you may need to remove another item, such as an OperatorFilterItem (for example, AND). If you do not remove unnecessary items from the filter, an error is returned when you try to view the report.

Parameters:

index - The index of the FilterItem object to be removed from Filter.

Returns:

An int that specifies the removed index.

Throws:

ReportSDKException

removeItemEx

public int removeItemEx(int index,
                        boolean repair)
                 throws ReportSDKException

Removes a FilterItem object from an array of FilterItems in the Filter object. The index is zero-based.

This method removes a single filter item from the array. If you want to replace the entire filter with a modified one, use the modify method.

Once a filter item has been removed, you may need to remove another item, such as an OperatorFilterItem (for example, AND). If you do not remove unnecessary items from the filter, an error is returned when you try to view the report.

Parameters:

index - The index of the FilterItem object to be removed from Filter.

repair - true if the Filter should be repaired, false otherwise.

Returns:

An int that specifies the removed index.

Throws:

ReportSDKException

getFormulaText

public java.lang.String getFormulaText()

Returns the filter formula text for a particular record or group filter

If there are FilterItem objects (either FieldRangeFilterItem objects or OperatorFilterItem objects) stored in the FilterItems collection, a string representation of the filter is returned. If there is no FilterItem object stored in the FilterItems collection, the FreeEditingText property of the Filter object is returned. The FreeEditingText property of the Filter object is a custom selection formula that cannot be parsed.

Returns:

String the formula text as described above

See Also:

setFormulaText(java.lang.String)

setFormulaText

public void setFormulaText(java.lang.String text)
                    throws ReportSDKException

Modifies the filter formula text for a particular record or group filter.

This method will store the formula string in the FreeEditingText property of the Filter object. The FreeEditingText property of the Filter object is a custom selection formula that cannot be parsed.

Parameters:

text - text of the formula to be set. This formula is used as a filter for either a record or a group.

Throws:

ReportSDKException

See Also:

getFormulaText()