|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface IFilter
This interface defines filters that are used in record selection and group selection. As the name
implies, they are used to select specified data. Initially, the filter is a simple string written
in Crystal syntax. When the file is opened, the string is parsed into an array of
FilterItems, which is stored in the Filter object's FilterItems property.
This is done in such a way that the string is broken up into data components and operator
components that act on the data. These components are stored as FieldRangeFilterItem and
OperatorFilterItem objects respectively. They are stored in the FilterItems
object in the same order that they appear in the formula string. Changing the position of the
objects in the array alters the functionality of the formula. Essentially, the
FieldRangeFilterItem object is a primitive expression that is joined with other primitive
expressions using a OperatorFilterItem object.
Consider a simple record selection formula such as: {Customer.Country} = "USA".
This formula filters out all records that do not have the country field equal to USA; it is
stored in the FreeEditingText property. After this string is parsed, the FilterItems
object will contain one FieldRangeFilterItem object because there is only one data
item used to filter the records. There is no OperatorFilterItem object because
there is only one primitive expression: the OperatorFilterItem is used to indicate
how two primitive expressions are combined.
The FieldRangeFilterItem contains four properties:
> operator
were used, this would indicate whether the expression would use >= or simply >.
Only the less than or greater than operations use this property.canFilterOn
method in the RecordFilterController and the GroupFilterController.ConstantValue object that stores "USA".
Note: If the formula were expanded to include an additional field so that the formula looked
like {Customer.Country} = "USA" AND {Customer.Region} = "CA", the resulting FilterItems
object would contain the following:
FieldRangeFilterItem ({Customer.Country} = "USA")OperatorFilterItem (AND)FieldRangeFilterItem ({Customer.Region} = "CA")OperatorFilterItem object to combine the two primitive expressions
({Customer.Country} = "USA" , {Customer.Region} = "CA"). The OperatorFilterItem
object has a method getOperator() to indicate which operator is
used to combine the two expressions; in this case it would be the string "AND".
Tip: When parentheses are included in a complex expression, each parenthesis is parsed
into a OperatorFilterItem.
Once the file is opened, and if the filter strings are parsed, the FreeEditingText property that stored these strings is emptied. If the formula is too complex and could not be parsed, the FilterItems property collection is empty and the FreeEditingText property remains. When modifying a filter you have two options:
Be aware, however, that if you use the one property to modify the filter, the other will not be automatically updated. That is, if you modify the FreeEditingText property, it is not re-parsed and the results are not stored in the FilterItems property. You should use only one of these properties per session.
Note: The modifications you make to a filter are saved only if you have used a
controller. Use the
GroupFilterController
and the
RecordFilterController
to modify the group formula and record formula respectively.
| Method Summary | |
|---|---|
java.lang.String |
computeText()
Returns a String representation of the field value that can be used in a
report formula. |
java.lang.String |
displayText(FieldDisplayNameType displayNameType,
java.util.Locale locale)
Returns a UI-friendly string representation of the filter. |
FilterItems |
getFilterItems()
Returns the result of a parsed filter string. |
FilterType |
getFilterType()
For internal use only |
FormulaNullTreatment |
getFormulaNullTreatment()
Returns how to treat null values in the evaluation of a formula. |
java.lang.String |
getFreeEditingText()
Returns the formula text that was originally used to define the filter. |
java.lang.String |
getName()
Returns the name of the filter. |
void |
setFilterItems(FilterItems filterItems)
Sets the result of a parsed filter string. |
void |
setFilterType(FilterType filterType)
For internal use only |
void |
setFormulaNullTreatment(FormulaNullTreatment treatment)
Sets how to treat null values in the evaluation of a formula. |
void |
setFreeEditingText(java.lang.String freeEditingText)
Sets the formula text that will be used to define the filter. |
void |
setName(java.lang.String name)
Sets the name of the filter. |
| Method Detail |
|---|
java.lang.String computeText()
Returns a String representation of the field value that can be used in a
report formula. The string is not formatted or localized. The syntax will always be Crystal
syntax.
If the field contains a date, computeText returns Date(x, x, x);
if it contains a date and time, computeText returns
DateTime(x, x, x, x, x, x). However, when the date is 1900, 0, 1 (the Java
start date), computeText returns Time(x, x, x). If you want to
set a field to a time value only (that is, with no date), you should set the date to 1900, 0,
1, so that computeText will retrieve the correct information.
String representation of the field value that can be used in a
report formula.
java.lang.String displayText(FieldDisplayNameType displayNameType,
java.util.Locale locale)
Returns a UI-friendly string representation of the filter. This method attempts to structure the filter formula as close to a localized phrase as possible. If you do not pass in a locale, it attempts to localize the string using the user's default locale.
If the field contains a date, displayText returns a locale-specific Date
string; if it contains a date and time, displayText returns a locale-specific
DateTime string; if it contains a time string, displayText returns a
locale-specific Time string.
displayNameType - Indicates how the name of the field is displayed.locale - Localizes the string according to a specific locale.
FilterItems getFilterItems()
Returns the result of a parsed filter string. When a filter string is parsed, it is broken into the following categories:
FieldRangeFilterItem).
OperatorFilterItem).
getFreeEditingText method to check whether the formula was
parsed successfully. If it is empty, then the parsing was successful.
Note: If you modify the filter using this method, the FreeEditingText property will not be updated.
FilterItems object containing the result of a parsed filter string.FilterType getFilterType()
java.lang.String getFreeEditingText()
Returns the formula text that was originally used to define the filter. This
String will be empty if the formula was successfully parsed into the
FilterItems property. If the formula text was too complicated to be parsed, this property
will still contain the formula text and the getFilterItems method
will return null.
Note: If you modify the filter using this property, the FilterItems property will not be updated until the file is saved and reopened--regardless of whether the initial parsing was successful or not.
String containing the formula text that was originally used to
define the filter.java.lang.String getName()
String containing the name of the filter.void setFilterItems(FilterItems filterItems)
Sets the result of a parsed filter string. When a filter string is parsed, it is broken into the following categories:
FieldRangeFilterItem).
OperatorFilterItem).
getFreeEditingText method to check whether the formula was
parsed successfully. If it is empty, then the parsing was successful.
Note: If you modify the filter using this method, the FreeEditingText property will not be updated.
filterItems - A FilterItems object containing the result of a parsed
filter string.void setFilterType(FilterType filterType)
void setFreeEditingText(java.lang.String freeEditingText)
Sets the formula text that will be used to define the filter. This String will
be empty if the formula is successfully parsed into the FilterItems property. If the formula
text is too complicated to be parsed, this property will still contain the formula text and
the getFilterItems method will return null.
Note: If you modify the filter using this property, the FilterItems property will not be updated until the file is saved and reopened--regardless of whether the initial parsing was successful or not.
freeEditingText - A String containing the formula text that was
originally used to define the filter.void setName(java.lang.String name)
name - A String containing the name of the filter.FormulaNullTreatment getFormulaNullTreatment()
Returns how to treat null values in the evaluation of a formula.
By default, null values are treated as exceptions, which means that as soon as RAS encounters a null valued field in a formula, it immediately stops evaluating the formula and produces no value.
If you want to handle null field values in your formula, you must explicitly do so by adding a test function such as IsNull(). You also have the option to treat nulls as default values. The following are the default values for different types used in a formula.
FormulaNullTreatment object that specifies how to treat
null values in the evaluation of a formula.void setFormulaNullTreatment(FormulaNullTreatment treatment)
Sets how to treat null values in the evaluation of a formula.
By default, null values are treated as exceptions, which means that as soon as RAS encounters a null valued field in a formula, it immediately stops evaluating the formula and produces no value.
If you want to handle null field values in your formula, you must explicitly do so by adding a test function such as IsNull(). You also have the option to treat nulls as default values. The following are the default values for different types used in a formula.
treatment - The FormulaNullTreatment object that specifies how to treat null values
in the evaluation of a formula.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||