| Lescasse Consulting |
| Home Company News Prices Download Buy Forums |
|
|
Printer Friendly
See also: TExcel5 is an object designed to let you use Microsoft Excel in your APL+Win applications.
You can, for example, use TExcel5:
As for other APL+Win Objects™, TExcel5 does not show itself by default when you instanciate it:
'ee'Œwi'*Create' 'TExcel5'
However you may show TExcel5 as you instantiate.
'ee'Œwi'*Create' 'TExcel5'('visible'1)
TExcel1.gif
Note that when doing so, TExcel5 shows up but with no workbook opened. To open TExcel5 and create a workbook at the same time, use the AddBook method:
'ee'Œwi'*Create' 'TExcel5' 'AddBook'('visible'1)
TExcel2.gif
By default the AddBook method creates a workbook with 2 or 3 worksheets (2 in our case here). To instanciate TExcel5 with a workbook containing only one worksheet do:
'ee'Œwi'*Create' 'TExcel5'('AddBook'1)('visible'1)
TExcel3.gif
Finally, you may want to set TExcel5 to stay on top of all other windows by setting its ontop property:
'ee'Œwi'*Create' 'TExcel5'('AddBook'1)('visible'1)('ontop'1)
Since, most of the time, you want to create TExcel5 as done just above, I have created a Show method for TExcel5 which does the same. Use it this way:
'ee'Œwi'*Create' 'TExcel5' 'Show'
If you want to use Show but don't want to let TExcel5 stay on top of your other windows:
'ee'Œwi'*Create' 'TExcel5' 'Show'('ontop'0)
As usual with other APL+Win Objects™, the class property returns the object class name:
'ee'Œwi'class' TExcel5
and the help property returns a complete example showing how to use TExcel5.
At any time after having creating an instance of TExcel5, you may query its hwnd read-only property which returns the Excel window handle.
Example:
'ee'Œwi'hwnd' 41026856
You may subsequently use this handle with Windows API to further use Excel in your application.
2œŒwcall'GetWindowText'('ee'Œwi'hwnd')(255½Œtcnul)255 Microsoft Excel - Book1
When you work with the TExcel5 object, it is generally to create or format a worksheet for display on the screen or for printing it. This often means setting a large number of TExcel5 properties and calling numerous methods. Many of these properties and methods update the Excel sheet. However you are generally only interested in the result, not in the intermediate states.
In order to avoid visually updating the worksheet when making changes to it, you can set the screenupdating property to 0 and rest it to 1 after everything is done. This has several advantages:
l it completely suppresses the flickering due to numerous worksheet visual updates l it considerably speeds up the process of building your worksheet programmatically
So the recommended way of working is something like:
’ MyExcelProgram;Z [1] [2] Z„'ee'Œwi'*Create' 'TExcel5'('AddBook'1) [3] Z„'ee'Œwi'screenupdating'0 [4] © Do as many updates to the Excel sheet as needed below [5] © ... [6] © ... [7] Z„'ee'Œwi'screenupdating'1 [8] Z„'ee'Œwi'visible'1 [9] © or: [10] © Z„'ee'Œwi'Print' [11] ’
At times you may want to start showing the Excel interface as soon as possible, for example to let know the user that an Excel sheet is being constructed: but the last thing you want to do is to let your user start clicking in this sheet and modifying it! So you can set the interactive property to 0 at the beginning and reset it to 1 at the end of your building process. The sample program becomes:
’ MyExcelProgram2;Z [1] [2] Z„'ee'Œwi'*Create' 'TExcel5'('AddBook'1) [3] Z„'ee'Œwi'interactive'0 [4] Z„'ee'Œwi'screenupdating'0 [5] Z„'ee'Œwi'visible'1 [6] © Do as many updates to the Excel sheet as needed below [7] © ... [8] © ... [9] Z„'ee'Œwi'screenupdating'1 [10] Z„'ee'Œwi'interactive'1 [11] © Maybe: [12] © Z„'ee'Œwi'Print' [13] ’
There are several ways a TExcel5 object can be deleted.
First you may programmatically call its Quit or Close method:
'ee'Œwi'Quit'
Second, you may close the instance of TExcel5 with your mouse by simply closing Excel. However this does not remove Excel from memory.
'ee'Œwi'*self'
If you want to remove Excel from memory, you must still call its Quit method.
It is important to note that unlike standard APL+Win Objects™, if you create and show 2 instances of TExcel5 with the same name, you end up having 2 Excel processes running at the same time. Example:
'ee'Œwi'*Create' 'TExcel5' 'Show'
Now press Ctrl+Alt+Del and display Windows Task Manager:
TExcel4.gif
Therefore if you don't pay attention, you may quickly eat your memory!
So, the good rule is: whenever you want to create an instance of TExcel5, first delete any instance of the same name which may already be running. For this purpose I have create the small handy Excel utility function , which reads as follows:
' Excel
Whenever you create an instance of TExcel5 use 2 instructions similar as the ones in function Excel.
Note that the SessionFocus method is not a TExcel5 method: it is inherited from TObject5 and returns the focus to the APL session as soon as TExcel5 is instanciated.
There is a deleteatclose proprety which helps you govern if TExcel5 deletes the object instance when the user closes the Excel document or not. By default deleteatclose is set to 1, but you may change it to be 0.
'ee'Œwi'deleteatclose' 1
Note: since Excel does not close its COM object when the user closes the TExcel5 window, deleteatclose has been implemented using a Timer to delete the TExcel5 instance. This Timer fires only once.
The language property is a read-only property which returns a 3-element vector of the country codes (LCID's) for:
l the install language l the user interface language l the Help language
Example:
'ee'Œwi'language' 1033 1033 1033
Installing APL Data Within An Excel Sheet
Let's now create an instance of TExcel5 with a workbook containing 2 worksheets and let's populate it with data coming from APL:
'ee'Œwi'Quit'
TExcel5.gif
In the above expression 1 represents the 1st worksheet and (2 2) the cell B2 (line 2 column 2).
Use the Add method to send any nested matrix to any TExcel5 worksheet:
'ee'Œwi'Add'2 'A1'(3 2½'APL+Win' 1200.12 'APL+Dos' 0 'APL+Unix' 123.48)
Let's use the sheet property to display Sheet2:
'ee'Œwi'sheet'2
TExcel6.gif
Now assume we want to add dates in column C and currency data in column D.
The Add method uses by default the xValue2 Excel property to install data in the worksheet. xValue2 is available with all versions of Excel but is not able of deal with Dates and Currencies. Another Excel property, xValue can install Dates and Currencies with a worksheet. Unfortunately its syntax has been changed by Microsoft for Excel XP.
But the Add method can deal with all this complexity: in order to tell the Add method to use Dates or Currencies, simply specify a 4th argument of 7 to convert integers to dates:
'ee'Œwi'Add'2(1 3)(3 1½37668+¼3)7
TExcel7.gif
Since the C column is not wide enough to display the dates, let's use the TExcel AutoFit method:
'ee'Œwi'AutoFit'
TExcel8.gif
Then let's add currency data in column D by specifying a conversion type of 6
'ee'Œwi'Add'2(1 4)(3 1½37668+¼3)6
To clear columns C and D, we could use the Clear method:
'ee'Œwi'Clear'2'C1:D3'
This clears range C1:D3 in sheet 2.
If we had wanted to install both columns in one instruction we should have used:
'ee'Œwi'Add'2(1 3)(3 2½2/37668+¼3)(3 2½7 6)
In order to install all 4 columns at once in one instruction, we need to know the data conversion types for strings and real numbers. Let's query the Add method documentation:
'ee'Œwi'?Add'
So we should use:
'ee'Œwi'Clear'
Whenever possible, use the Add with no 4th argument, since it's a bit faster.
If a range has already been defined, it's also possible and faster to use the value property. This property accepts a scalar, a vector or an APL matrix as its only argument.
Example:
Excel 'ee'Œwi'Add'1(1 1)(10 10½¼100) 'ee'Œwi'range'1(2 2 5 3) 'ee'Œwi'value' 12 13 14 22 23 24 32 33 34 42 43 44 52 53 54 'ee'Œwi'value'(100×'ee'Œwi'value')
Except for a few properties like the xValue and xValue2 properties, Excel is only able to apply a property to one cell at a time.
We, APLers, would prefer to be able to apply a matrix of properties to a range of cells.
This is why I added the ApplyMatrixProperty method.
To better understand it, let's assume you would like to alternate background colors at every cell of a range of cells. Here is how you would do it:
Excel
TExcel10.gif
This results in the following effect:
This would have been quite tedious to achieve without the ApplyMatrixProperty. You may use the ApplyMatrixProperty with any property which can be applied to a range of cells.
Use the Clear method to clear one or more cells in a given sheet. Its first argument is the sheet number or name. Its optional second argument is the range of cells to clear (either a range in 'A5:D12' format or a 2-element or 4-element integer vector representing the top left and bottom right cells of the range):
'ee'Œwi'Clear'1 4 4 5 6 'ee'Œwi'Clear'1(4 4 5 6) 'ee'Œwi'Clear'1'D4:F5'
Please note that the Clear method removes everything from the cell, i.e. the content of the cell, the formula it contains but also any formatting applied to the cell (for example background colors, borders, etc.)
To clear a whole sheet:
'ee'Œwi'Clear'1 'ee'Œwi'Clear' 'Sheet1'
These last expressions clear all cells in the 1st worksheet.
If you only want to remove the cell content and formula, but not its formatting, use the Empty method.
The Empty methods arguments are the same as the Clear method ones.
Example:
'ee'Œwi'Empty'1'D4:F5'
resulting in the following effect where the formatting of cells D4 to F5 has not been deleted:
Use the Get method to read data from the worksheet
Excel
'ee'Œwi'Get'0 1 1 3 4
The first argument is the sheet number from which to retrieve data: use 0 or '' to retrieve data from the active sheet.
The other arguments represent the top left cell coordinates and the bottom right cell coordinates of the rectangle of cells to retrieve.
'ee'Œwi'Get'0 2 2 3 4
You may also retrieve data from another sheet without leaving the one you are in:
'ee'Œwi'AddSheet' '' 'Sheet1'1
'ee'Œwi'Get'2 1 1 5 6
Empty cells are returned as empty character vectors:
]display 'ee'Œwi'Get'2 1 1 5 6
It is often not wished to get an heterogeneous array result, especially when retrieving numeric data from a sheet: with the Get method empty cells generate character empty vectors in the result.
That's why TExcel5 provides a GetNum method which is identical to the Get method except that it returns 0 instead of character vectors for all cells containing character data.
'ee'Œwi'GetNum'2
You can specify only a sheet number with no cell coordinates. In this case Get returns the whole worksheet set of data up to the last used cell.
'ee'Œwi'Get'2
To retrieve the content of all worksheets at once, do not specify any argument to the Get method:
'ee'Œwi'Get'
'ee'Œwi'GetNum'
]display 'ee'Œwi'GetNum'
TExcel5_67.gif
To load an existing Excel workbook, use the Load method as follows:
'ee'Œwi'Load' 'o:\excel\dvd.xls'
This method returns 0 if TExcel succeeds in loading the specified workbook: it returns 1 otherwise:
'ee'Œwi'Load' 'o:\excel\dvd9.xls'
It returned 1 here since file 'o:\excel\dvd9.xls' does not exist on my system.
Note that using the Load method creates a new workbook, i.e. you will find one more item at the bottom of the Excel Windows menu.
If you do not provide any path, the Load method will search for the document in the default file path. You may get or set the defaultfilepath property to know about or change the default file path:
'ee'Œwi'defaultfilepath' C:\Documents and Settings\Eric Lescasse\My Documents
'ee'Œwi'defaultfilepath' 'c:\temp' 'ee'Œwi'defaultfilepath' c:\temp
You may sometimes want to load a delimited records text file into Excel. In order to do that, you need to use the loaddelim property to specify the character which serves as a delimitor in the text file. The possible delimiters are:
Note: this property is currently reserved for future use
At times, you may want to import a complete worksheet or workbook into APL. To do so, use the Import method. Here is how to import all worksheets from workbook o:\excel\dvd.xls:
½'ee'Œwi'Import' 'o:\excel\dvd.xls'
½¨'ee'Œwi'Import' 'o:\excel\dvd.xls'
Note that the Import method would close any workbook already opened which would be called 'o:\excel\dvd.xls' If we want to import only worksheet 2 from this workbook:
½'ee'Œwi'Import' 'o:\excel\dvd.xls'2
If we wanted to import only range 'B2:F10' from sheet 1 of this workbook:
½'ee'Œwi'Import' 'o:\excel\dvd.xls'1'B2:F10'
'ee'Œwi'Import' 'o:\excel\dvd.xls'1'B2:F10'
Note that the Import method does not show Excel and works in the background so that you may silently import Excel files data into your APL+Win application.
Conversely, it is sometimes useful to create an Excel workbook with data coming from an APL application.
You may use the Export method in order to do so, as follows:
'ee'Œwi'Export' 'c:\temp\trial.xls'2(1 1)(10 10½¼100)
The above instruction creates a new Excel workbook called trial.xls in the c:\temp directory: this workbook has 2 worksheets and the second worksheet contains a 10 by 10 matrix of the first 100 integers.
Note that the Export method does not show Excel and works in the background so that you may silently produce Excel files from an APL+Win application.
Once you have loaded several workbooks (i.e. Excel files) into TExcel, use the booknames property to retrieve their names:
'ee'Œwi'booknames'
]display 'ee'Œwi'booknames'
TExcel5_68.gif
Note that the workbook name retrieved is the name which follows Microsoft Excel - in the workbook caption.
To activate a workbook, use the book property and pass a workbook name (or number) to it:
'ee'Œwi'book'1
'ee'Œwi'book' 'dvd.xls'
This operation returns 0 if it succeeds, 1 otherwise.
Note that book is case insensitive.
To retrieve the currently active workbook number, simply query the book property:
'ee'Œwi'book'
To retrieve the currently active workbook name, simply query the bookname property:
'ee'Œwi'bookname'
Once you have loaded a workbook (i.e. an Excel file) into TExcel, use the sheetnames read-only property to retrieve the worksheet names of all the worksheets it contains:
'ee'Œwi'book'1
To activate a given worksheet, use the sheet property passing to it the worksheet name (or number):
'ee'Œwi'sheet'2
This property returns 0 if the worksheet could be activated and 1 if it could not be activated (for example if the specified worksheet does not exist).
You may also specify a sheet by its name as in:
'ee'Œwi'sheet' 'Sheet1'
At any times you may use the sheet (or sheetname) property to query the active worksheet number (or name):
'ee'Œwi'sheet'
To rename a worksheet, use the sheetname property (not the sheet property which activates worksheets but does not rename them):
'ee'Œwi'sheet'2
'ee'Œwi'sheetname'
To close a workbook call the CloseWorkbook method with the workbook number or name as an argument (or with no argument to close the active workbook):
'ee'Œwi'CloseWorkbook' 'dvd.xls'
This method returns 0 if operation was successful, 1 otherwise.
'ee'Œwi'CloseWorkbook' 'dvd.xls'
The CloseWorkbook methode returned 1 because dvd.xls was already closed.
'ee'Œwi'CloseWorkbook'
This last instruction closes the active workbook since no workbook was specified. Note that this leaves Excel opened with no workbook opened.
You can use the AutoFit method to auto adjust column with for the best fit to data contained in the columns.
If you call this function with no argument, it applies to the whole currently active worksheet:
Excel
Its first argument, if specified, must be a sheet number or a sheet name.
Its second argument, if specified, must be a range of cells. If you specify '' as the second argument, the AutoFit method applies to the currently defined range in the specified sheet (note in this case that the currently defined range may have been defined in another sheet).
'ee'Œwi'AddSheet' '' 'Sheet1'1
This last command applied to all columns containing data in worksheet 2.
'ee'Œwi'AutoFit'1(3 4 10 16)
This last command applied to range of cells spanning from cell 3 4 (D3) to cell 10 16 (P10).
If you want to add a sheet to an open workbook, use the AddSheet method.
The question rises of where to insert the new sheet compared to the existing sheets.
Let's start from this situation:
'ee'Œwi'AddSheet' 'Sheet2' ''2
This instruction inserts 2 sheets before Sheet2: the new sheets are automatically numbered Sheet3 and Sheet4 by Excel and the lastly created sheet (Sheet4) is activated. Note the worksheets order.
Note that the 2 worksheets are inserted in reverse order: Sheet4 then Sheet3
'ee'Œwi'AddSheet' '' 'Sheet4'1
The following instruction inserts a new sheet (Sheet5) after Sheet4.
Using AddSheet with no arguments inserts a sheet after the last worksheet.
'ee'Œwi'AddSheet'
Use the DeleteSheet to delete worksheets from a workbook.
The DeleteSheet method accepts a sheet number or sheet name as its only argument. We highly recommend that you always use a sheet name when using this method. Since an Excel workbook may NOT have 0 worksheets, the DeleteSheet method inserts a new worksheet before deleting the last worksheet in a workbook.
Example:
'ee'Œwi'DeleteSheet' 'Sheet6'
Note that the DeleteSheet method may be used with no argument to delete the active worksheet:
'ee'Œwi'sheet' 'Sheet5'
There are 2 methods for saving workbooks: Save and SaveAs.
The Save method takes no argument and saves the active workbook to its original folder replacing the original file.
When using Save to save a new workbook which you created with the AddBook method, the workbook is saved into the C:\Documents and Settings\...\My Documents folder. It is generally preferable to use the SaveAs method to save a new workbook. You must pass the complete Excel file name to the SaveAs method or the file will be saved into C:\Documents And Settings\<your user name>\My Documents:
'ee'Œwi'SaveAs' 'c:\temp\book2.xls'
| ||||||||||||||||||||||||||||||||||||||||||||||