GetExcelSheetList, ScriptGetExcelSheetList Methods

Applies To

fpSpread control

Description

Returns a handle to the Excel workbook and a list of the sheet names in the specified Excel-formatted file.

Syntax

C++

BOOL CSpreadSheet::GetExcelSheetList(LPCTSTR FileName, const VARIANT& VarArray, short* ListCount, LPCTSTR LogFileName, short* WorkbookHandle, BOOL Replace);

Visual Basic

fpSpread.GetExcelSheetList(ByVal FileName As String, VarArray As Variant, ListCount As Integer, ByVal LogFileName As String, WorkbookHandle As Integer, ByVal Replace As Boolean) As Boolean

Note: The ScriptGetExcelSheetList method uses the same syntax except method parameters that are not passed "ByVal" are declared as variants. For more information on Script methods, see Scripting Environment Usage.

Parameters

The following parameters are available:

Parameter	Description
FileName	Path and file name of the file for which you want to return the sheet list
List	A string or variant array containing the list of sheet names See Remarks section for more information.
ListCount	Returns the total number of sheets in the specified Excel workbook
LogFileName	Specifies the path and file name of the log file created when Spread creates the sheet list If you do not provide a file name, the import will not create a log file. If you do not want to create a log file, set to "".
WorkbookHandle	Returns the handle to the workbook from the Excel-formatted file
Replace	Specifies whether to read all the information from the specified file, or just the sheet information

Remarks

Excel-formatted files can contain multiple sheets; however, Spread can only import one sheet at a time from an Excel-formatted file. Use this method to return a handle to the workbook and a list of the sheets in an Excel workbook.

This method is called for the current sheet setting unless you first set the Sheet property to specify the sheet with which you want to work.

For best results, first declare an empty array, and then call the GetExcelSheetList method passing Null as the List parameter to find out the number of worksheets in the Excel-formatted file. Then redimension the List array according to the number of worksheets in the Excel-formatted file, returned in the ListCount parameter. Finally, call the GetExcelSheetList method again with the array as the List parameter. For more detailed information, see Loading an Excel-Formatted File.

The workbook handle returned by the method is an identifier that represents an Excel workbook that was opened by the Spread import process. The handle is global: if your project contains other fpSpread controls, or multiple projects are running that contain fpSpread controls, any of the fpSpread controls can use the workbook handle created by the import process. This is similar to how controls can share fonts and colors.

Workbook handles provide the benefit of opening the Excel file only once, as well as reducing storage requirements, providing faster sheet requests, and providing the ability to access multiple Excel workbook sheets simultaneously across controls and applications.

When the application opens an Excel file for importing, the import process loads the "global" portion of the Excel file and returns the list of sheet names and the workbook handle to the application. After the initial "global" load, the application (or any application that contains an fpSpread control) can load any of the sheets in the Excel file using the workbook handle.

If the application needs to query the sheet list again, you can use the GetExcelSheetList method with the same initial parameters, except the Replace parameter. You can set the Replace parameter to False if you do not need to get the refreshed version of the Excel file, and can therefore use the global information from the initial load. Set the Replace parameter to True if you need to get the refreshed version of the Excel file, including the new global information.

The array returned by the method contains a list of the names of the sheets in the specified file. When you call the ImportExcelSheet method, you can use one of the names in the array to specify the sheet to import, or you can refer to the sheet by its index in the list. If you use the sheet number, remember that the sheet numbers are zero-based.

For instructions and more information about importing Excel-formatted files, see Loading an Excel-Formatted File and Excel-Formatted File Import/Export (online PDF manual). Excel-Formatted File Import/Export includes a list and description of the log message numbers.

Note: Call this method if you use the Spread control in a scripting environment (for example, Microsoft's Visual InterDev or Internet Explorer) or a non-scripting environment. However, if you want to use the Spread control in a scripting environment and you want to change any parameter that is not passed "ByVal", you must set the ScriptEnhanced property to True and call the ScriptGetExcelSheetList method. ScriptGetExcelSheetList method parameters that are not passed "ByVal" are declared as variants.

Return Type

True if successful; otherwise, False.

DLL Correspondence

SSGetExcelSheetList function