ig.excel.Workbook
Remarks
Every workbook consists of one or more worksheets (Worksheet). The default constructor creates an empty workbook.
Dependencies
-
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.
-
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.
-
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:
- Create new font format with Workbook.createNewWorkbookFont,
- Set all necessary properties on given font format,
- 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:
- Create new cell format with Workbook.createNewWorksheetCellFormat,
- Set all necessary properties on given cell format,
- 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.
-
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.
-
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 <a href="ig.excel.WorksheetTable.html">WorksheetTable</a> 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.
-
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.
-
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
- The function to call when the Workbook has been successfully loaded.
- failCallback
- Type:function
- The function to call when loading the Workbook has resulted in an error.
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
- The function to call when the Workbook has been successfully loaded.
- failCallback
- Type:function
- The function to call when loading the Workbook has resulted in an error.
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.
-
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.
-
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.
-
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.
- allowEditStructure
- Type:boolean
- Optional
- Optional boolean indicating the new value for the WorkbookProtection.allowEditStructure.
- allowEditWindows
- Type:boolean
- Optional
- Optional boolean indicating the new value for the WorkbookProtection.allowEditWindows.
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
- The function to call when the Workbook has been successfully saved into a Uint8Array or base-64 encoded string.
- failCallback
- Type:function
- The function to call when saving the Workbook has caused an error.
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
- The function to call when the Workbook has been successfully saved into a Uint8Array or base-64 encoded string.
- failCallback
- Type:function
- The function to call when saving the Workbook has caused an error.
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.
-
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