com.f1j.ss.pivot
Interface Field

public interface Field

extends Lockable

This interface defines the PivotRange field API.

Method Summary

Item	addCalculatedItem(java.lang.String name, java.lang.String formula) Creates a new calculated item with the given name and formula in US English.
Item	addCalculatedItemLocal(java.lang.String name, java.lang.String formula) Creates a new calculated item with the given name and formula in user's language.
void	applyFieldGroupDef(FieldGroupDef definition) Applies the specified group definition to this field.
boolean	canAddToArea(Area area) Indicates if this field can be added to the specified area.
void	checkCanAddCalculatedItem() Throws a DataConflictException if calculated items are not allowed.
void	checkCanShowDateGroupDialog() Throws a DataConflictException if the Date Group Dialog is not allowed.
void	checkCanShowFieldSettings() Throws a DataConflictException if the Field Settings Dialog is not allowed.
void	checkCanShowItemFilterDlg() Throws a DataConflictException if the Item Filter Dialog is not allowed.
void	checkCanShowNumericGroupDialog() Throws a SelectionException if the Numeric Group Dialog is not allowed.
FieldGroupDef	createFieldGroupDef() Creates a default grouping definition for this field.
void	deleteCalculatedItem(java.lang.String name) Deletes the calculated item with the given name.
Item	getCalculatedItem(int index) Returns the calculated item in this field at the given index.
int	getCalculatedItemCount() Returns the number of calculated items in this field.
RowColumnFieldSettings	getDataFieldSettings() Returns a field settings object for the data field.
FieldGroupDef	getFieldGroupDef() If this field is grouped, then the definition of the group is returned.
FieldSettings	getFieldSettings() Returns a field settings object for the current field.
java.lang.String	getFormula() Returns the formula for a calculated field in US English.
java.lang.String	getFormulaLocal() Returns the formula for a calculated field in the user's language.
Item	getItem(int index) Returns the Item in this field located at the given index.
Item	getItem(java.lang.String name) Returns the Item in this field with the specified name.
int	getItemCount() Returns the number of items in this field.
java.lang.String	getName() Returns the name of the field.
PivotRange.EArea	getOrientation() Returns the orientation of this field as an enumeration of PivotRange.EArea.
Item	getPage() Returns the name of the page item that this field is filtering on.
Item[]	getPageItems() Returns an array of the items in the field.
int	getPosition() Returns the position of this field in the containing Area.
java.lang.String	getSourceName() Returns the field’s name as it appears in the original source data for this PivotRange report.
Field	getSummary(int index) Returns the summary field located at the given index.
int	getSummaryCount() Returns the number of summary fields in this field.
SummaryFieldSettings	getSummaryFieldSettings() Returns a field settings object for the summary field.
boolean	hasCalculatedItem() Returns the presence of calculated items in this field.
void	hide() Causes this Field to become hidden.
boolean	isCalculated() Indicates if this field is a calculated field.
boolean	isDataField() Indicates if this field is the Data Field.
boolean	isDeleted() Indicates if this field is no longer part of the PivotRange.
boolean	isGrouped() Indicates if this field is grouped.
boolean	isInner() Indicates if this field is the inner field of the Row or Column Area.
boolean	isNumeric() Indicates if this field contains all numeric data.
boolean	isSummary() Indicates if this field is a summary field.
void	setDataFieldSettings(RowColumnFieldSettings settings) Sets the field settings for the data field.
void	setFieldSettings(FieldSettings settings) Sets the field settings for this field.
void	setFormula(java.lang.String formula) Sets the formula for a calculated field in US English.
void	setFormulaLocal(java.lang.String formula) Sets the formula for a calculated field in the user's language.
void	setName(java.lang.String name) Sets the name of the field.
void	setPage(Item page) Sets the page item that this field should filter on.
void	setPage(java.lang.String page) Sets the page item that this field should filter on.
void	setPosition(int position) Sets the position of this field in the containing Area.
void	setSummaryFieldSettings(SummaryFieldSettings settings) Sets the field settings for this field.
void	ungroup() Removes any grouping that has been applied to this field.

Methods inherited from interface com.f1j.util.Lockable

getLock, releaseLock

Method Detail

addCalculatedItem

public Item addCalculatedItem(java.lang.String name,
                              java.lang.String formula)
                       throws DataConflictException,
                              DuplicateNameException,
                              InvalidPivotRangeException,
                              F1Exception

Creates a new calculated item with the given name and formula in US English. If a calculated item with this name already exists, then the new formula is applied.

Parameters:

name - The name of the calculated item.

formula - The formula for the calculated item.

Returns:

The calculated item.

Throws:

DataConflictException - if the PivotRange would grow too large.

DuplicateNameException - if an item already exists with the specified name.

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Item

addCalculatedItemLocal

public Item addCalculatedItemLocal(java.lang.String name,
                                   java.lang.String formula)
                            throws InvalidPivotRangeException,
                                   F1Exception

Creates a new calculated item with the given name and formula in user's language. If a calculated item with this name already exists, then the new formula is applied.

Parameters:

name - The name of the calculated item.

formula - The formula for the calculated item.

Returns:

The calculated item.

Throws:

DataConflictException - if the PivotRange would grow too large.

DuplicateNameException - if an item already exists with the specified name.

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Item

applyFieldGroupDef

public void applyFieldGroupDef(FieldGroupDef definition)
                        throws InvalidPivotRangeException,
                               DataConflictException,
                               SelectionException,
                               F1Exception

Applies the specified group definition to this field.

Parameters:

definition - The group definition for this field.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

DataConflictException - if the PivotRange would grow too large.

SelectionException - if this field cannot be grouped by date or number.

F1Exception - if an error occurs.

Since:

11.0

See Also:

FieldGroupDef

canAddToArea

public boolean canAddToArea(Area area)

Indicates if this field can be added to the specified area.

Parameters:

area - The desired area for adding the field.

Since:

11.0

checkCanAddCalculatedItem

public void checkCanAddCalculatedItem()
                               throws DataConflictException,
                                      InvalidPivotRangeException,
                                      F1Exception

Throws a DataConflictException if calculated items are not allowed.

Throws:

DataConflictException - if calculated item would conflict with other fields.

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

checkCanShowDateGroupDialog

public void checkCanShowDateGroupDialog()
                                 throws InvalidPivotRangeException,
                                        F1Exception

Throws a DataConflictException if the Date Group Dialog is not allowed.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

checkCanShowFieldSettings

public void checkCanShowFieldSettings()
                               throws InvalidPivotRangeException,
                                      F1Exception

Throws a DataConflictException if the Field Settings Dialog is not allowed.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

checkCanShowItemFilterDlg

public void checkCanShowItemFilterDlg()
                               throws InvalidPivotRangeException,
                                      F1Exception

Throws a DataConflictException if the Item Filter Dialog is not allowed.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

checkCanShowNumericGroupDialog

public void checkCanShowNumericGroupDialog()
                                    throws InvalidPivotRangeException,
                                           F1Exception

Throws a SelectionException if the Numeric Group Dialog is not allowed.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

createFieldGroupDef

public FieldGroupDef createFieldGroupDef()
                                  throws InvalidPivotRangeException,
                                         F1Exception

Creates a default grouping definition for this field. If items within this field are not all dates or numbers, returns null.

Returns:

The default grouping definition for this field.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

FieldGroupDef

deleteCalculatedItem

public void deleteCalculatedItem(java.lang.String name)
                          throws InvalidPivotRangeException,
                                 F1Exception

Deletes the calculated item with the given name.

Parameters:

name - The name of the calculated item.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Item

getCalculatedItem

public Item getCalculatedItem(int index)

Returns the calculated item in this field at the given index.

Returns:

The calculated item located at the given index.

Since:

11.0

See Also:

Item

getCalculatedItemCount

public int getCalculatedItemCount()

Returns the number of calculated items in this field.

Returns:

Number of calculated items in this field.

Since:

11.0

See Also:

Item

hasCalculatedItem

public boolean hasCalculatedItem()

Returns the presence of calculated items in this field.

Returns:

presence of calculated items in this field.

Since:

11.0

See Also:

Item

getDataFieldSettings

public RowColumnFieldSettings getDataFieldSettings()

Returns a field settings object for the data field. Only valid when this field is the data field.

Returns:

Field settings object for this field.

Since:

11.0

See Also:

RowColumnFieldSettings

getFieldGroupDef

public FieldGroupDef getFieldGroupDef()

If this field is grouped, then the definition of the group is returned. If this field is not grouped, then a default definition is returned.

Returns:

The group definition for this field.

Since:

11.0

See Also:

FieldGroupDef

getFieldSettings

public FieldSettings getFieldSettings()

Returns a field settings object for the current field. Only valid when this field is not the data field or a summary field.

Returns:

Field settings object for this field.

Since:

11.0

See Also:

FieldSettings

getFormula

public java.lang.String getFormula()

Returns the formula for a calculated field in US English. If not a calculated field, returns null.

Returns:

The formula in a calculated field.

Since:

11.0

getFormulaLocal

public java.lang.String getFormulaLocal()

Returns the formula for a calculated field in the user's language. If not a calculated field, returns null.

Returns:

The formula in a calculated field.

Since:

11.0

getItem

public Item getItem(int index)
             throws com.f1j.util.InvalidIndexException,
                    F1Exception

Returns the Item in this field located at the given index.

Parameters:

index - The index of the desired item within this field.

Returns:

The Item located at the given index.

Throws:

com.f1j.util.InvalidIndexException - if the index is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Item

getItem

public Item getItem(java.lang.String name)

Returns the Item in this field with the specified name.

Parameters:

name - The name of the desired item within this field.

Returns:

The item with the specified name.

Since:

11.0

See Also:

Item

getItemCount

public int getItemCount()

Returns the number of items in this field.

Returns:

Number of items in this field.

Since:

11.0

See Also:

Item

getName

public java.lang.String getName()

Returns the name of the field.

Returns:

The name of the field.

Since:

11.0

getOrientation

public PivotRange.EArea getOrientation()

Returns the orientation of this field as an enumeration of PivotRange.EArea.

Returns:

Orientation of this field as a PivotRange.EArea.

Since:

11.0

See Also:

PivotRange.EArea

getPage

public Item getPage()
             throws DataConflictException,
                    F1Exception

Returns the name of the page item that this field is filtering on. Returns null if no filter has been specified. Only valid for fields in the Page area.

Returns:

The filtering item in this page field.

Throws:

DataConflictException - if the field is not in page area.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Item

getPageItems

public Item[] getPageItems()
                    throws DataConflictException,
                           F1Exception

Returns an array of the items in the field. Only valid for fields in the Page area.

Returns:

An array of the items in the field.

Throws:

DataConflictException - if the field is not in page area.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Item

getPosition

public int getPosition()

Returns the position of this field in the containing Area.

Returns:

Position of field in the containing Area.

Since:

11.0

See Also:

Area

getSourceName

public java.lang.String getSourceName()

Returns the field’s name as it appears in the original source data for this PivotRange report. This might be different from the current field name if the user renamed the field after creating the PivotRange report.

Returns:

Original field name.

Since:

11.0

getSummary

public Field getSummary(int index)
                 throws DataConflictException,
                        com.f1j.util.InvalidIndexException,
                        F1Exception

Returns the summary field located at the given index. This field must be the data field.

Parameters:

index - The index of the desired summary in the data field.

Returns:

The summary field located at the given index.

Throws:

DataConflictException - if this would make PivotRange too large.

com.f1j.util.InvalidIndexException - if index is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Item

getSummaryCount

public int getSummaryCount()

Returns the number of summary fields in this field. This field must be the data field.

Returns:

Number of summary fields in the data field.

Since:

11.0

See Also:

Item

getSummaryFieldSettings

public SummaryFieldSettings getSummaryFieldSettings()

Returns a field settings object for the summary field. Only valid when this field is a summary field.

Returns:

Field settings object for this field.

Since:

11.0

See Also:

SummaryFieldSettings

hide

public void hide()
          throws AccessDeniedException,
                 InvalidPivotRangeException,
                 SelectionException,
                 F1Exception

Causes this Field to become hidden.

Throws:

AccessDeniedException - if sheet is protected.

InvalidPivotRangeException - if the PivotRange is invalid.

SelectionException - if the field is currently hidden.

F1Exception - if an error occurs.

Since:

11.0

isCalculated

public boolean isCalculated()

Indicates if this field is a calculated field.

Returns:

boolean. true = if field is a calculated field.

Since:

11.0

isDataField

public boolean isDataField()

Indicates if this field is the Data Field.

Returns:

boolean. true = if field is data field.

Since:

11.0

isDeleted

public boolean isDeleted()

Indicates if this field is no longer part of the PivotRange.

Returns:

true if the field is no longer part of the PivotRange.

isGrouped

public boolean isGrouped()

Indicates if this field is grouped.

Returns:

boolean. true = if field is grouped.

Since:

11.0

isInner

public boolean isInner()

Indicates if this field is the inner field of the Row or Column Area.

Returns:

boolean. true = if field is inner field.

Since:

11.0

isNumeric

public boolean isNumeric()

Indicates if this field contains all numeric data.

Returns:

boolean. true = if field contains numeric data.

Since:

11.0

isSummary

public boolean isSummary()

Indicates if this field is a summary field.

Returns:

boolean. true = if field is a summary.

Since:

11.0

setDataFieldSettings

public void setDataFieldSettings(RowColumnFieldSettings settings)
                          throws DataConflictException,
                                 InvalidPivotRangeException,
                                 F1Exception

Sets the field settings for the data field. Only valid when this field is the data field.

Parameters:

settings - Field settings object for this field.

Throws:

DataConflictException - if trying to hide all items.

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

RowColumnFieldSettings

setFieldSettings

public void setFieldSettings(FieldSettings settings)
                      throws InvalidPivotRangeException,
                             F1Exception

Sets the field settings for this field. Only valid when this field is not the data field or a summary field.

Parameters:

settings - Field settings object for this field.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

FieldSettings

setFormula

public void setFormula(java.lang.String formula)
                throws AccessDeniedException,
                       DataConflictException,
                       DuplicateNameException,
                       InvalidPivotRangeException,
                       F1Exception

Sets the formula for a calculated field in US English. Only valid if field is calculated field.

Parameters:

formula - The formula to use in the calculated field.

Throws:

AccessDeniedException - if the sheet is protected.

DataConflictException - if the PivotRange would grow too large.

DuplicateNameException - if an item already exists with the specified name.

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

setFormulaLocal

public void setFormulaLocal(java.lang.String formula)
                     throws AccessDeniedException,
                            DataConflictException,
                            DuplicateNameException,
                            InvalidPivotRangeException,
                            F1Exception

Sets the formula for a calculated field in the user's language. Only valid if field is calculated field.

Parameters:

formula - The formula to use in the calculated field.

Throws:

AccessDeniedException - if the sheet is protected.

DataConflictException - if the PivotRange would grow too large.

DuplicateNameException - if an item already exists with the specified name.

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

setName

public void setName(java.lang.String name)
             throws InvalidPivotRangeException,
                    com.f1j.ss.pivot.InvalidNameException,
                    DuplicateNameException,
                    F1Exception

Sets the name of the field.

Parameters:

name - The name of the field.

Since:

11.0

setPage

public void setPage(java.lang.String page)
             throws InvalidPivotRangeException,
                    DataConflictException,
                    F1Exception

Sets the page item that this field should filter on. Specifying null will remove page filtering on this field. Only valid for fields in the Page area.

Parameters:

page - The name of the item on which to filter.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

DataConflictException - if the field is not in page area.

F1Exception - if an error occurs.

Since:

11.0

setPage

public void setPage(Item page)
             throws InvalidPivotRangeException,
                    DataConflictException,
                    F1Exception

Sets the page item that this field should filter on. Specifying null will remove page filtering on this field. Only valid for fields in the Page area.

Parameters:

page - The item on which to filter.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

DataConflictException - if the field is not in page area.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Item

setPosition

public void setPosition(int position)
                 throws AccessDeniedException,
                        InvalidPivotRangeException,
                        DataConflictException,
                        SelectionException,
                        F1Exception

Sets the position of this field in the containing Area.

Parameters:

position - The position of field in the containing Area.

Throws:

AccessDeniedException - if sheet is protected.

DataConflictException - if PivotRange would grow too large.

InvalidPivotRangeException - if the PivotRange is invalid.

SelectionException - if field is a summary or is not in an area.

F1Exception - if an error occurs.

Since:

11.0

See Also:

Area

setSummaryFieldSettings

public void setSummaryFieldSettings(SummaryFieldSettings settings)
                             throws InvalidPivotRangeException,
                                    F1Exception

Sets the field settings for this field. Only valid when this field is a summary field.

Parameters:

settings - Field settings object for this field.

Throws:

InvalidPivotRangeException - if the PivotRange is invalid.

F1Exception - if an error occurs.

Since:

11.0

See Also:

SummaryFieldSettings

ungroup

public void ungroup()
             throws F1Exception

Removes any grouping that has been applied to this field.

Throws:

F1Exception - if an error occurs.

Since:

11.0.1