ig.excel.Workbook

Represents a Microsoft Excel workbook.

Remarks

Every workbook consists of one or more worksheets (Worksheet). The default constructor creates an empty workbook.

Dependencies

jquery-1.4.4.js
infragistics.util.js
infragistics.ext_collections.js
infragistics.ext_collectionsExtended.js
infragistics.ext_io.js
infragistics.ext_text.js
infragistics.ext_core.js
infragistics.documents.core_core.js
infragistics.ext_ui.js

  • maxExcel2007CellFormatCount

    Type:
    number
    Default:
    64000

    Maximum number of distinct cell formats in the workbook allowed by the Excel 2007 file format.

  • maxExcel2007ColumnCount

    Type:
    number
    Default:
    16384

    Maximum number of columns in the worksheet allowed by the Excel 2007 file format.

  • maxExcel2007RowCount

    Type:
    number
    Default:
    1048576

    Maximum number of rows in the worksheet allowed by the Excel 2007 file format.

  • maxExcelCellFormatCount

    Type:
    number
    Default:
    4000

    Maximum number of distinct cell formats in the workbook allowed by the Excel 97-2003 file format.

  • maxExcelColumnCount

    Type:
    number
    Default:
    256

    Maximum number of columns in the worksheet allowed by the Excel 97-2003 file format.

  • maxExcelRowCount

    Type:
    number
    Default:
    65536

    Maximum number of rows in the worksheet allowed by the Excel 97-2003 file format.

  • maxExcelWorkbookFonts

    Type:
    number
    Default:
    512

    Maximum number fonts in a workbook allowed by Excel.

The current widget has no events.

  • ig.excel.Workbook
    Constructor

    new $.ig.excel.Workbook( );

    Creates a new instance of the Workbook class.

    Remarks

    The new workbook created is empty. At least one Worksheet must be added to it before it can be saved.

    See Also

  • ig.excel.Workbook
    Constructor

    new $.ig.excel.Workbook( format:ig.excel.WorkbookFormat );

    Creates a new instance of the Workbook class.

    • format
    • Type:ig.excel.WorkbookFormat
    • The file format to use when imposing format restrictions and saving.

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException format is not defined in the WorkbookFormat enumeration.

    Remarks

    The new workbook created is empty. At least one Worksheet must be added to it before it can be saved.

    See Also

  • calculationMode

    .calculationMode( );
    Return Type:
    ig.excel.CalculationMode
    Return Type Description:
    The value which indicates how a formula will be recalculated when a referenced value changes.

    Gets the value which indicates how a formula will be recalculated when a referenced value changes.

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException The assigned value is not defined in the Workbook.calculationMode enumeration.

    Remarks

    If this is set to a value of Manual, the Workbook.recalculateBeforeSave property will determine if formulas are recalculated just before saving the file. Otherwise, that property is ignored.

    See Also

  • calculationMode

    .calculationMode( value:ig.excel.CalculationMode );
    Return Type:
    ig.excel.CalculationMode
    Return Type Description:
    The value which indicates how a formula will be recalculated when a referenced value changes.

    Sets the value which indicates how a formula will be recalculated when a referenced value changes.

    • value
    • Type:ig.excel.CalculationMode

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException The assigned value is not defined in the Workbook.calculationMode enumeration.

    Remarks

    If this is set to a value of Manual, the Workbook.recalculateBeforeSave property will determine if formulas are recalculated just before saving the file. Otherwise, that property is ignored.

    See Also

  • cellReferenceMode

    .cellReferenceMode( );
    Return Type:
    ig.excel.CellReferenceMode
    Return Type Description:
    The value which indicates the way cells in the workbook are referenced.

    Gets the value which indicates the way cells in the workbook are referenced.

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException The assigned value is not defined in the Workbook.cellReferenceMode enumeration.

    Remarks

    The value of this property will affect the row and columns labels of the workbook when opened in Microsoft Excel. In addition, it will affect the display of formulas referencing different cells.

  • cellReferenceMode

    .cellReferenceMode( value:ig.excel.CellReferenceMode );
    Return Type:
    ig.excel.CellReferenceMode
    Return Type Description:
    The value which indicates the way cells in the workbook are referenced.

    Sets the value which indicates the way cells in the workbook are referenced.

    • value
    • Type:ig.excel.CellReferenceMode

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException The assigned value is not defined in the Workbook.cellReferenceMode enumeration.

    Remarks

    The value of this property will affect the row and columns labels of the workbook when opened in Microsoft Excel. In addition, it will affect the display of formulas referencing different cells.

  • characterWidth256thsToPixels

    .characterWidth256thsToPixels( characterWidth256ths:number );
    Return Type:
    number
    Return Type Description:
    The number of pixels equivalent to the characterWidth256ths value.

    Converts units of 1/256s of the average character width to pixels.

    • characterWidth256ths
    • Type:number
    • The number of units of 1/256s of the average character width.

    Remarks

    The units of 1/256s of the average character width are based on the font height of the normal style.

    See Also

  • clearConnectionData

    .clearConnectionData( );

    Clears all external data connections from the Workbook.

  • clearPivotTableData

    .clearPivotTableData( );

    Clears all pivot tables and associated slicers from the Workbook.

  • createNewWorkbookFont

    .createNewWorkbookFont( );
    Return Type:
    ig.excel.IWorkbookFont
    Return Type Description:
    The created excel font object.

    Factory method which creates new workbook font.

    Remarks

    IWorkbookFont describes font used in excel workbook. If many parts of excel workbook have same and complex (more than one property in common) font formatting, use this method in following manner:

    1. Create new font format with Workbook.createNewWorkbookFont,
    2. Set all necessary properties on given font format,
    3. Apply font format to all excel objects which use it with IWorkbookFont.setFontFormatting method.

    Use of this procedure will simplify you code for complex font formats and increase speed of resulting program. It will not reduce total number of font formats in a workbook as font formats are internally cached no matter which method is used.

  • createNewWorksheetCellFormat

    .createNewWorksheetCellFormat( );
    Return Type:
    ig.excel.IWorksheetCellFormat
    Return Type Description:
    The cell format which was created.

    Creates new worksheet cell format.

    Remarks

    IWorksheetCellFormat describes cell specific formatting (font, number format, appearance etc.). Total number of different cell formats in excel workbook is limited to Workbook.maxExcelCellFormatCount. If many parts of excel workbook have same and complex (more than one property in common) cell formatting, use this method in following manner:

    1. Create new cell format with Workbook.createNewWorksheetCellFormat,
    2. Set all necessary properties on given cell format,
    3. Apply cell format to all excel objects which use it with IWorksheetCellFormat.setFormatting method.

    Use of this procedure will simplify you code for complex cell formats and increase speed of resulting program. It will not reduce total number of cell formats in a workbook as cell formats are internally cached no matter which method is used.

  • culture

    .culture( );
    Return Type:
    string
    Return Type Description:
    The current culture for the workbook or Null to use the thread's current culture.

    Gets the culture to use as the current culture for the workbook when doing any culture-aware conversions or comparisons.

    Remarks

    Note: The culture is not saved or loaded in workbook files, so this is only used at when accessing and manipulating objects owned or associated with the Workbook.

  • culture

    .culture( value:string );
    Return Type:
    string
    Return Type Description:
    The current culture for the workbook or Null to use the thread's current culture.

    Sets the culture to use as the current culture for the workbook when doing any culture-aware conversions or comparisons.

    • value
    • Type:string

    Remarks

    Note: The culture is not saved or loaded in workbook files, so this is only used at when accessing and manipulating objects owned or associated with the Workbook.

  • currentFormat

    .currentFormat( );

    Gets the current format of the workbook. This is the format which will be used when saving and imposing format restrictions.

    See Also

  • customTableStyles

    .customTableStyles( );

    Gets the collection of custom table styles in the workbook.

    See Also

  • customTableStyles

    .customTableStyles( index:number );
    Return Type:
    ig.excel.WorksheetTableStyle
    Return Type Description:
    The WorksheetTableStyle instance at the specified index.

    Gets the WorksheetTableStyle at the specified index.

    • index
    • Type:number
    • The index at which to get the WorksheetTableStyle.

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException index is less than 0 or greater than or equal to CustomTableStyleCollection.count.

  • customTableStyles

    .customTableStyles( name:string );
    Return Type:
    ig.excel.WorksheetTableStyle
    Return Type Description:
    The WorksheetTableStyle instance with the specified name or null if a table style with that name does not exist.

    Gets the WorksheetTableStyle with the specified name.

    • name
    • Type:string
    • The name of the WorksheetTableStyle to find.

    Remarks

    Table style names are compared case-insensitively.

  • customViews

    .customViews( );
    Return Type:
    ig.excel.CustomViewCollection
    Return Type Description:
    The collection of custom views for the workbook.

    Gets the collection of custom views for the workbook.

    Remarks

    Each custom view stores display settings and optionally print settings, which can later be applied to the workbook and its worksheets as one operation, through both the Microsoft Excel UI and the Excel assembly by calling the CustomView.apply method.

    See Also

  • customViews

    .customViews( index:number );
    Return Type:
    ig.excel.CustomView
    Return Type Description:
    The custom view at the specified index.

    Gets the custom view at the specified index.

    • index
    • Type:number
    • The zero-based index of the custom view to get.

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException index is less than zero or index is greater than or equal to CustomViewCollection.count.

  • dateSystem

    .dateSystem( );
    Return Type:
    ig.excel.DateSystem
    Return Type Description:
    The date system used internally by Microsoft Excel.

    Gets the date system used internally by Microsoft Excel.

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException The assigned value is not defined in the Workbook.dateSystem enumeration.

  • dateSystem

    .dateSystem( value:ig.excel.DateSystem );
    Return Type:
    ig.excel.DateSystem
    Return Type Description:
    The date system used internally by Microsoft Excel.

    Sets the date system used internally by Microsoft Excel.

    • value
    • Type:ig.excel.DateSystem

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException The assigned value is not defined in the Workbook.dateSystem enumeration.

  • defaultTableStyle

    .defaultTableStyle( );

    Gets the default style for tables in the workbook.

    Exceptions

    Exception Description
    ig.ArgumentException The specified value is not in the Workbook.customTableStyles or Workbook.standardTableStyles collections.

    Remarks

    This can be set to any WorksheetTableStyle in the Workbook.customTableStyles or Workbook.standardTableStyles collection.

    This will never return a null value. If it is set to null, it will be reset to the TableStyleMedium2 table style.

    If this value is changed, it will not be applied to existing tables in the workbook. Only newly created tables will use default table style on the workbook.

    See Also

  • defaultTableStyle

    .defaultTableStyle( value:ig.excel.WorksheetTableStyle );

    Sets the default style for tables in the workbook.

    • value
    • Type:ig.excel.WorksheetTableStyle

    Exceptions

    Exception Description
    ig.ArgumentException The specified value is not in the Workbook.customTableStyles or Workbook.standardTableStyles collections.

    Remarks

    This can be set to any WorksheetTableStyle in the Workbook.customTableStyles or Workbook.standardTableStyles collection.

    This will never return a null value. If it is set to null, it will be reset to the TableStyleMedium2 table style.

    If this value is changed, it will not be applied to existing tables in the workbook. Only newly created tables will use default table style on the workbook.

    See Also

  • documentProperties

    .documentProperties( );
    Return Type:
    ig.excel.DocumentProperties
    Return Type Description:
    The properties associated with the workbook document.

    Gets the properties associated with the workbook document.

    Remarks

    The document properties are pieces of information which provide details on the content of the workbook, such as the author, title, and subject of the workbook.

  • getMaxColumnCount

    .getMaxColumnCount( format:ig.excel.WorkbookFormat );
    Return Type:
    number
    Return Type Description:
    The maximum number of columns supported by the format.

    Returns the number of columns that are supported by the specified format.

    • format
    • Type:ig.excel.WorkbookFormat
    • The format used by the workbook.

  • getMaxRowCount

    .getMaxRowCount( format:ig.excel.WorkbookFormat );
    Return Type:
    number
    Return Type Description:
    The maximum number of rows supported by the format.

    Returns the number of rows that are supported by the specified format.

    • format
    • Type:ig.excel.WorkbookFormat
    • The format used by the workbook.

  • getTable

    .getTable( name:string );
    Return Type:
    ig.excel.WorksheetTable
    Return Type Description:
    A WorksheetTable instance if a table exists with the specified name; Otherwise null.

    Gets the table with the specified name.

    • name
    • Type:string
    • The name of the table to get.

    Remarks

    Table names are compared case-insensitively.

  • getWorkbookFormat

    .getWorkbookFormat( fileName:string );
    Return Type:
    ig.excel.WorkbookFormat
    Return Type Description:
    The workbook format based on the file extension of the file, or null if the correct format cannot be determined.

    Returns the WorkbookFormat based on the file extension of the specified file.

    • fileName
    • Type:string
    • The filename of an excel file.

  • hasProtectionPassword

    .hasProtectionPassword( );

    Returns a boolean indicating if the Workbook has been protected with a password.

    Remarks

    When protecting a Workbook, a password is optional. The HasProtectionPassword will return true if the Workbook is currently protected (see Workbook.isProtected) and a password was specified when it was protected. To protect a Workbook without a password, one may use the Workbook.protect method that doesn't take a password.

    See Also

  • isProtected

    .isProtected( );

    Returns a boolean indicating if the Workbook has been protected.

    Remarks

    The IsProtected property will return true if the Workbook is currently protected. When a Workbook is protected certain operations related to the Worksheets displayed or their order or the properties of the windows for the Workbook may be restricted based on the values of the Workbook.protection.

    See Also

  • isSaving

    .isSaving( );

    Gets the value indicating whether the Workbook is currently being saved.

  • isValidFunctionName

    .isValidFunctionName( functionName:string );
    Return Type:
    boolean
    Return Type Description:
    True if the function will be recognized in Microsoft Excel; False otherwise.

    Gets a value indicating whether the specified function will be recognized and solved by Microsoft Excel when the workbook is saved out.

    • functionName
    • Type:string
    • The case-insensitive name of the function.

  • isWorkbookEncrypted

    .isWorkbookEncrypted( stream:object );
    Return Type:
    boolean
    Return Type Description:
    True if the stream contains a workbook which is encrypted; False otherwise

    Determines whether the workbook in the specified stream is encrypted with an open password.

    • stream
    • Type:object
    • The stream to check for encryption.

    Exceptions

    Exception Description
    ig.ArgumentNullException Occurs when stream is null.

  • iterativeCalculationsEnabled

    .iterativeCalculationsEnabled( );
    Return Type:
    boolean
    Return Type Description:
    The value which indicates whether iterations are allowed while calculating recursive formulas.

    Gets the value which indicates whether iterations are allowed while calculating formulas containing circular references.

    Remarks

    When iterative calculations are enabled, a formula is allowed to use circular references, or directly or indirectly reference the cell to which it belongs. Microsoft Excel stops iteratively calculating formulas after iterating Workbook.maxRecursionIterations times or when all formula values change by less than Workbook.maxChangeInIteration between two iterations.

    When iterative calculations are disabled, circular references are not allowed, and a formula which references the cell to which it belongs, directly or indirectly, will cause Microsoft Excel to show an error message and the cell will contain a Circularity error.

    See Also

  • iterativeCalculationsEnabled

    .iterativeCalculationsEnabled( value:boolean );
    Return Type:
    boolean
    Return Type Description:
    The value which indicates whether iterations are allowed while calculating recursive formulas.

    Sets the value which indicates whether iterations are allowed while calculating formulas containing circular references.

    • value
    • Type:boolean

    Remarks

    When iterative calculations are enabled, a formula is allowed to use circular references, or directly or indirectly reference the cell to which it belongs. Microsoft Excel stops iteratively calculating formulas after iterating Workbook.maxRecursionIterations times or when all formula values change by less than Workbook.maxChangeInIteration between two iterations.

    When iterative calculations are disabled, circular references are not allowed, and a formula which references the cell to which it belongs, directly or indirectly, will cause Microsoft Excel to show an error message and the cell will contain a Circularity error.

    See Also

  • load

    .load( data:object, loadOptions:ig.excel.WorkbookLoadOptions, successCallback:function, failCallback:function );

    Loads a workbook from a Uint8Array or base64 encoded string.

    • data
    • Type:object
    • The data from which to load the workbook.
    • loadOptions
    • Type:ig.excel.WorkbookLoadOptions
    • The options to use to load the stream or null to use the default options.
    • successCallback
    • Type:function
    • failCallback
    • Type:function

    Exceptions

    Exception Description
    ig.ArgumentException data does not contain valid Microsoft Excel file contents.
    ig.ArgumentException The file format cannot be determined from the specified stream.
    ig.InvalidOperationException The format of the workbook data is in an unsupported format.
    ig.NotSupportedException The workbook being loaded is in an Excel 2007 format and the CLR 2.0 Excel assembly is being used. The overload taking an IPackageFactory must be used in this case so the Excel 2007 file package can be accessed.
    ig.documentsCore.DocumentEncryptedException Occurs when the workbook is encrypted.

    Remarks

    When loading the workbook, the contents of the file will be examined to try to determine the format. The Workbook.currentFormat of the resulting workbook will indicate the format the workbook was loaded from.

  • load

    .load( data:object, successCallback:function, failCallback:function );

    Loads a workbook from a Uint8Array or base64 encoded string.

    • data
    • Type:object
    • The data from which to load the workbook.
    • successCallback
    • Type:function
    • failCallback
    • Type:function

    Exceptions

    Exception Description
    ig.ArgumentException data does not contain valid Microsoft Excel file contents.
    ig.ArgumentException The file format cannot be determined from the specified stream.
    ig.InvalidOperationException The format of the workbook data is in an unsupported format.
    ig.NotSupportedException The workbook being loaded is in an Excel 2007 format and the CLR 2.0 Excel assembly is being used. The overload taking an IPackageFactory must be used in this case so the Excel 2007 file package can be accessed.
    ig.documentsCore.DocumentEncryptedException Occurs when the workbook is encrypted.

    Remarks

    When loading the workbook, the contents of the file will be examined to try to determine the format. The Workbook.currentFormat of the resulting workbook will indicate the format the workbook was loaded from.

  • maxChangeInIteration

    .maxChangeInIteration( );
    Return Type:
    number
    Return Type Description:
    The maximum change of the values in a formula between iterations which will exit from iteration.

    Gets the maximum change of the values in a formula between iterations which will exit from iteration.

    Remarks

    This property is only valid when Workbook.iterativeCalculationsEnabled is True. Otherwise it is ignored.

    When iterative calculations, or circular references, are enabled, this property determines the maximum change in all values of a formula between two iterations that will cause the formula to exit iterative calculations. Iterative calculations will also be stopped if the formula iterates Workbook.maxRecursionIterations times.

    See Also

  • maxChangeInIteration

    .maxChangeInIteration( value:number );
    Return Type:
    number
    Return Type Description:
    The maximum change of the values in a formula between iterations which will exit from iteration.

    Sets the maximum change of the values in a formula between iterations which will exit from iteration.

    • value
    • Type:number

    Remarks

    This property is only valid when Workbook.iterativeCalculationsEnabled is True. Otherwise it is ignored.

    When iterative calculations, or circular references, are enabled, this property determines the maximum change in all values of a formula between two iterations that will cause the formula to exit iterative calculations. Iterative calculations will also be stopped if the formula iterates Workbook.maxRecursionIterations times.

    See Also

  • maxColumnCount

    .maxColumnCount( );

    Gets the maximum number of columns allowed in each worksheet based on the Workbook.currentFormat.

  • maxRecursionIterations

    .maxRecursionIterations( );
    Return Type:
    number
    Return Type Description:
    The maximum number of times formulas should be iteratively calculated.

    Gets the maximum number of times formulas should be iteratively calculated.

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException The assigned value is outside the valid range of 1 and 32767.

    Remarks

    This property is only valid when Workbook.iterativeCalculationsEnabled is True. Otherwise it is ignored.

    When iterative calculations, or circular references, are enabled, this property determines the number of iterations allowed when calculating iteratively.

    See Also

  • maxRecursionIterations

    .maxRecursionIterations( value:number );
    Return Type:
    number
    Return Type Description:
    The maximum number of times formulas should be iteratively calculated.

    Sets the maximum number of times formulas should be iteratively calculated.

    • value
    • Type:number

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException The assigned value is outside the valid range of 1 and 32767.

    Remarks

    This property is only valid when Workbook.iterativeCalculationsEnabled is True. Otherwise it is ignored.

    When iterative calculations, or circular references, are enabled, this property determines the number of iterations allowed when calculating iteratively.

    See Also

  • maxRowCount

    .maxRowCount( );

    Gets the maximum number of rows allowed in each worksheet based on the Workbook.currentFormat.

  • namedReferences

    .namedReferences( );
    Return Type:
    ig.excel.NamedReferenceCollection
    Return Type Description:
    The collection of named references in the workbook.

    Gets the collection of named references in the workbook.

    Remarks

    Named references are typically used to refer to cells or ranges of cells by name. The named reference names are used by formulas instead of explicitly naming the cells or cell ranges.

    See Also

  • namedReferences

    .namedReferences( index:number );
    Return Type:
    ig.excel.NamedReference
    Return Type Description:
    The named reference at the specified index.

    Gets the named reference at the specified index.

    • index
    • Type:number
    • The zero-based index of the named reference to get.

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException index is less than zero or index is greater than or equal to NamedReferenceCollection.count.

  • palette

    .palette( );

    Gets the color palette used when the saved file is opened in Microsoft Excel 2003 and earlier versions.

    Remarks

    When the file is opened in Microsoft Excel 2003 and earlier versions, the actual colors used in cells and shapes may not be displayed. Instead, the closest color in the palette will be displayed instead. Therefore, the palette can be customized if necessary to keep the colors as accurate as possible in older versions of Excel.

  • palette

    .palette( index:number );

    Gets a color in the palette.

    • index
    • Type:number
    • The index of the color to get or set in the palette.

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException index is less than 0 or greater than 55.
    ig.ArgumentException The value assigned is an empty color, a system color, or is not opaque.

    Remarks

    When a color is set in the palette, WorkbookColorPalette.isCustom will return True. The palette can than be reset with the WorkbookColorPalette.reset method.

    Colors added to the palette must be opaque.

    See Also

  • palette

    .palette( index:number, value:string );

    Sets a color in the palette.

    • index
    • Type:number
    • The index of the color to get or set in the palette.
    • value
    • Type:string

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException index is less than 0 or greater than 55.
    ig.ArgumentException The value assigned is an empty color, a system color, or is not opaque.

    Remarks

    When a color is set in the palette, WorkbookColorPalette.isCustom will return True. The palette can than be reset with the WorkbookColorPalette.reset method.

    Colors added to the palette must be opaque.

    See Also

  • pixelsToCharacterWidth256ths

    .pixelsToCharacterWidth256ths( pixels:number );
    Return Type:
    number
    Return Type Description:
    The number of units of 1/256s of the average character width equivalent to the pixels value.

    Converts pixels to units of 1/256s of the average character width.

    • pixels
    • Type:number
    • The number of pixels.

    Remarks

    The units of 1/256s of the average character width are based on the font height of the normal style.

    See Also

  • precision

    .precision( );
    Return Type:
    ig.excel.Precision
    Return Type Description:
    The precision to use when obtaining a cell's value.

    Gets the precision to use when obtaining a cell's value.

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException The assigned value is not defined in the Precision enumeration.

    Remarks

    The precision determines whether to use the actual value of the cell or the display value of the cell. These are typically the same, but the format of a cell could cause a loss of precision in the displayed value. For example, if a cell's value is 18.975, and a currency format is used for the cell, the display value will be 18.98.

  • precision

    .precision( value:ig.excel.Precision );
    Return Type:
    ig.excel.Precision
    Return Type Description:
    The precision to use when obtaining a cell's value.

    Sets the precision to use when obtaining a cell's value.

    • value
    • Type:ig.excel.Precision

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException The assigned value is not defined in the Precision enumeration.

    Remarks

    The precision determines whether to use the actual value of the cell or the display value of the cell. These are typically the same, but the format of a cell could cause a loss of precision in the displayed value. For example, if a cell's value is 18.975, and a currency format is used for the cell, the display value will be 18.98.

  • protect

    .protect( [allowEditStructure:boolean], [allowEditWindows:boolean] );

    Protects the Workbook without a password.

    Remarks

    When a Workbook is protected without a password, the end user may unprotect the Workbook in Excel without having to supply a password. To programatically unprotect a Workbook, one may use the Workbook.unprotect method.

    When a Workbook is protected, the values of the properties of the WorkbookProtection instance from this Workbook's Workbook.protection property indicate the disabled operations.

    Note: If Workbook.isProtected is already true, the method will be ignored.

    See Also

  • protection

    .protection( );

    Returns an object that provides information used when the Workbook has been protected.

    See Also

  • recalculate

    .recalculate( );

    Recalculates all dirty formulas pending a calculation on the workbook.

    Remarks

    This can be used when the Workbook.calculationMode is Manual. In Manual mode, when cells are dirtied, formulas referencing those cells will not be recalculated until Recalculate is called or Workbook.recalculateBeforeSave is True and the workbook is saved.

    To force a recalculation of non-dirty formulas, use the Workbook.recalculate overload and specify True for the includeNonDirtyFormulas parameter.

    See Also

  • recalculate

    .recalculate( includeNonDirtyFormulas:boolean );

    Recalculates all formulas on the workbook.

    • includeNonDirtyFormulas
    • Type:boolean
    • True to recalculate all formulas on the workbook regardless of whether they had a pending evaluation. False to only calculate dirty formulas.

    Remarks

    This can be used when the Workbook.calculationMode is Manual. In Manual mode, when cells are dirtied, formulas referencing those cells will not be recalculated until Recalculate is called or Workbook.recalculateBeforeSave is True and the workbook is saved.

    See Also

  • recalculateBeforeSave

    .recalculateBeforeSave( );
    Return Type:
    boolean
    Return Type Description:
    The value which indicates whether the workbook should recalculate all formulas before saving.

    Gets the value which indicates whether the workbook should recalculate all formulas before saving.

    Remarks

    This property only applies if the Workbook.calculationMode is set to Manual. Otherwise, it is ignored.

    See Also

  • recalculateBeforeSave

    .recalculateBeforeSave( value:boolean );
    Return Type:
    boolean
    Return Type Description:
    The value which indicates whether the workbook should recalculate all formulas before saving.

    Sets the value which indicates whether the workbook should recalculate all formulas before saving.

    • value
    • Type:boolean

    Remarks

    This property only applies if the Workbook.calculationMode is set to Manual. Otherwise, it is ignored.

    See Also

  • registerUserDefinedFunction

    .registerUserDefinedFunction( userDefinedFunction:ig.excel.ExcelCalcFunction );
    Return Type:
    boolean
    Return Type Description:
    Returns true if the type was registered successfully, else false if the registration failed

    Registers a single ExcelCalcFunction instance.

    • userDefinedFunction
    • Type:ig.excel.ExcelCalcFunction
    • User defined function instance to register

    Remarks

    Users can build custom functions used in formulas by sub-classing the ExcelCalcFunction class. Once the derived class is instantiated it must be registered by using the RegisterUserDefinedFunction method before being available and referenced by a formulas.

  • resumeCalculations

    .resumeCalculations( );

    Resumes the calculation of formulas.

    Remarks

    If calculations were not suspended when this is called, it will have no effect.

    For each call to Workbook.suspendCalculations, a call to ResumeCalculations must be made. As soon as the number of calls to ResumeCalculations equals the number of calls to SuspendCalculations, calculations will be resumed.

    See Also

  • save

    .save( saveOptions:ig.excel.WorkbookSaveOptions, successCallback:function, failCallback:function );

    Writes the workbook to a Uint8Array.

    • saveOptions
    • Type:ig.excel.WorkbookSaveOptions
    • The options to use to save the stream or null to use the default options.
    • successCallback
    • Type:function
    • failCallback
    • Type:function

    Exceptions

    Exception Description
    ig.InvalidOperationException The workbook has no worksheets in its Workbook.worksheets collection.
    ig.InvalidOperationException No worksheet in this workbook's Worksheets collection has its DisplayOptions.visibility set to Visible.
    ig.InvalidOperationException A CustomView in the workbook's Workbook.customViews collection has all worksheets hidden. At least one worksheet must be visible in all custom views.

    Remarks

    The workbook will be written in the format specified by the Workbook.currentFormat.

    See Also

  • save

    .save( successCallback:function, failCallback:function );

    Writes the workbook to a Uint8Array.

    • successCallback
    • Type:function
    • failCallback
    • Type:function

    Exceptions

    Exception Description
    ig.InvalidOperationException The workbook has no worksheets in its Workbook.worksheets collection.
    ig.InvalidOperationException No worksheet in this workbook's Worksheets collection has its DisplayOptions.visibility set to Visible.
    ig.InvalidOperationException A CustomView in the workbook's Workbook.customViews collection has all worksheets hidden. At least one worksheet must be visible in all custom views.

    Remarks

    The workbook will be written in the format specified by the Workbook.currentFormat.

    See Also

  • saveExternalLinkedValues

    .saveExternalLinkedValues( );
    Return Type:
    boolean
    Return Type Description:
    The value which indicates whether to save values linked from external workbooks.

    Gets the value which indicates whether to save values linked from external workbooks.

    Remarks

    This value will only be used when the workbook is opened in Microsoft Excel. When referencing external values and saving a workbook through the Excel assembly, external linked values will never be saved.

  • saveExternalLinkedValues

    .saveExternalLinkedValues( value:boolean );
    Return Type:
    boolean
    Return Type Description:
    The value which indicates whether to save values linked from external workbooks.

    Sets the value which indicates whether to save values linked from external workbooks.

    • value
    • Type:boolean

    Remarks

    This value will only be used when the workbook is opened in Microsoft Excel. When referencing external values and saving a workbook through the Excel assembly, external linked values will never be saved.

  • screenDpi

    .screenDpi( );
    Return Type:
    object
    Return Type Description:
    This will be an object with numeric values for properties 'width' and 'height'.

    Gets the Dpi to use when calculating row and column sizes for the workbook. If empty, the system Dpi will be used.

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is not empty and does not have two positive values.

  • screenDpi

    .screenDpi( value:object );
    Return Type:
    object
    Return Type Description:
    This will be an object with numeric values for properties 'width' and 'height'.

    Sets the Dpi to use when calculating row and column sizes for the workbook. If empty, the system Dpi will be used.

    • value
    • Type:object
    • This can be an object with numeric values for properties 'width' and 'height', such as { width: 1, height: 2 }.

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is not empty and does not have two positive values.

  • setCurrentFormat

    .setCurrentFormat( format:ig.excel.WorkbookFormat );

    Sets the current format of the workbook.

    • format
    • Type:ig.excel.WorkbookFormat
    • The file format to use when imposing format restrictions and saving.

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException format is not defined in the WorkbookFormat enumeration.
    ig.InvalidOperationException The workbook already contains data which exceeds the limits imposed by format.

    See Also

  • shouldRemoveCarriageReturnsOnSave

    .shouldRemoveCarriageReturnsOnSave( );
    Return Type:
    boolean
    Return Type Description:
    True if the saved workbook file should not contain the carriage return characters from cell values; False to export the string values as they have been set on the cells.

    Gets the value which indicates whether carriage return characters should be removed from string values in cells when the workbook is saved to an Excel file.

    Remarks

    In Microsoft Excel 2003, carriage return characters are displayed as boxes. Most of the time, this should not be seen and removing the carriage return characters has no adverse effect on the layout of the text within a cell. Therefore, this property is True by default.

  • shouldRemoveCarriageReturnsOnSave

    .shouldRemoveCarriageReturnsOnSave( value:boolean );
    Return Type:
    boolean
    Return Type Description:
    True if the saved workbook file should not contain the carriage return characters from cell values; False to export the string values as they have been set on the cells.

    Sets the value which indicates whether carriage return characters should be removed from string values in cells when the workbook is saved to an Excel file.

    • value
    • Type:boolean

    Remarks

    In Microsoft Excel 2003, carriage return characters are displayed as boxes. Most of the time, this should not be seen and removing the carriage return characters has no adverse effect on the layout of the text within a cell. Therefore, this property is True by default.

  • standardTableStyles

    .standardTableStyles( );

    Gets the read-only collection of preset table styles in the workbook.

    See Also

  • standardTableStyles

    .standardTableStyles( index:number );
    Return Type:
    ig.excel.WorksheetTableStyle
    Return Type Description:
    The WorksheetTableStyle instance at the specified index.

    Gets the WorksheetTableStyle at the specified index.

    • index
    • Type:number
    • The index at which to get the WorksheetTableStyle.

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException index is less than 0 or greater than or equal to StandardTableStyleCollection.count.

  • standardTableStyles

    .standardTableStyles( name:string );
    Return Type:
    ig.excel.WorksheetTableStyle
    Return Type Description:
    The WorksheetTableStyle instance with the specified name or null if a table style with that name does not exist.

    Gets the WorksheetTableStyle with the specified name.

    • name
    • Type:string
    • The name of the WorksheetTableStyle to find.

    Remarks

    Table style names are compared case-insensitively.

  • styles

    .styles( );
    Return Type:
    ig.excel.WorkbookStyleCollection
    Return Type Description:
    The collection of custom styles in the workbook.

    Gets the collection of custom styles in the workbook.

    Remarks

    Use this collection to add custom styles to Excel workbook. The user can apply those styles to different parts of excel workbook and thereby set complex formatting with ease.

    See Also

  • styles

    .styles( index:number );
    Return Type:
    ig.excel.WorkbookStyle
    Return Type Description:
    The style at the specified index.

    Gets the style at the specified index.

    • index
    • Type:number
    • The zero-based index of the style to get.

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException index is less than zero or index is greater than or equal to WorkbookStyleCollection.count.

  • styles

    .styles( name:string );
    Return Type:
    ig.excel.WorkbookStyle
    Return Type Description:
    The style with the specified name or null if no style with that name exists.

    Gets the style with the specified name.

    • name
    • Type:string
    • The name of the style to get.

    Exceptions

    Exception Description
    ig.ArgumentNullException name is null.

    Remarks

    Style names are compared case-insensitively.

  • suspendCalculations

    .suspendCalculations( );

    Temporarily suspends the calculation of formulas.

    Remarks

    This should be used when adding many formulas or modifying large amounts of data on a workbook at once so formulas are not calculated each time cells are dirtied.

    For each call to SuspendCalculations, a call to Workbook.resumeCalculations must be made. As soon as the number of calls to ResumeCalculations equals the number of calls to SuspendCalculations, calculations will be resumed.

    See Also

  • unprotect

    .unprotect( );

    Removes the Workbook protection.

    See Also

  • validateFormatStrings

    .validateFormatStrings( );

    Gets the value indicating whether the format strings should be validated when they are set.

    Remarks

    This value is False by default to maintain backward compatibility.

    When True, format strings will be validated when a IWorksheetCellFormat.formatString property is set. An invalid format string will cause an exception. When False, invalid format strings will be allowed, but if the display text of a cell is requested, an exception will be thrown at that time. If invalid format strings are allowed and the workbook is saved and opened in Microsoft Excel, it will show an error.

    See Also

  • validateFormatStrings

    .validateFormatStrings( value:boolean );

    Sets the value indicating whether the format strings should be validated when they are set.

    • value
    • Type:boolean

    Remarks

    This value is False by default to maintain backward compatibility.

    When True, format strings will be validated when a IWorksheetCellFormat.formatString property is set. An invalid format string will cause an exception. When False, invalid format strings will be allowed, but if the display text of a cell is requested, an exception will be thrown at that time. If invalid format strings are allowed and the workbook is saved and opened in Microsoft Excel, it will show an error.

    See Also

  • windowOptions

    .windowOptions( );
    Return Type:
    ig.excel.WorkbookWindowOptions
    Return Type Description:
    The options which control various workbook level display properties.

    Gets the options which control various workbook level display properties.

    Remarks

    The window options control properties of the child MDI window showing the workbook in Microsoft Excel. They also control display options of the workbook which do not change based on the selected worksheet.

    See Also

  • worksheets

    .worksheets( );
    Return Type:
    ig.excel.WorksheetCollection
    Return Type Description:
    The collection of worksheets in the workbook.

    Gets the collection of worksheets in the workbook.

    Remarks

    Use WindowOptions.SelectedWorksheet to set the selected worksheet. The selected worksheet is the worksheet seen when the workbook is opened in Microsoft Excel.

  • worksheets

    .worksheets( index:number );
    Return Type:
    ig.excel.Worksheet
    Return Type Description:
    The worksheet at the specified index.

    Gets the worksheet at the specified index.

    • index
    • Type:number
    • The zero-based index of the worksheet to get.

    Exceptions

    Exception Description
    ig.ArgumentOutOfRangeException index is less than zero or index is greater than or equal to WorksheetCollection.count.

  • worksheets

    .worksheets( name:string );
    Return Type:
    ig.excel.Worksheet
    Return Type Description:
    The worksheet with the specified name.

    Gets the worksheet with the specified name.

    • name
    • Type:string
    • The name of the worksheet to get.

    Exceptions

    Exception Description
    ig.InvalidOperationException A worksheet with the specified name does not exist in the collection.

    Remarks

    Worksheet names are compared case-insensitively.

    See Also

Copyright © 1996 - 2024 Infragistics, Inc. All rights reserved.