TA B O G A NAT I VE E XCE L

TNATIVEEXCEL

L I BR ARY
TNativeExcel Library
INTRODUCTION

INTRODUCTION

The Taboga TNativeExcel library is a native excel biff format interface for writing
Excel 2003 files (BIFF8).
Using this library you can create Excel 2003 compatible workbooks including both
data and formulas from your Clarion application.

I N S TA L L AT I O N

To install the
TNativeExcel.EXE.
template.

library simply execute the included installation file

This program will carry out the installation and register the

Please note that the Native Excel library contains the full source code, and a
template to simplify its use within your application. The following table explains in
which directories the library will be installed:
Templates

TNativeExcel.TPL

Source
Code

TWorkbook.INC
TWorkbook.CLW
TWorkbook.EQU

Clarion 6
%ROOT
%\3rdparty\Template

%ROOT%\Libsrc

Clarion 7
C:\Program
Files\Softvelocity\Cla
rion
7\Accessory\Template
\Win
C:\Program
Files\Softvelocity\Cla
rion

Documenta
tion
Examples

TXLS8Engine.INC
TXLS8Engine.CLW
TXLS8CELL.INC
TXLS8CELL.CLW
TXLS8F.INC
TXLS8F.CLW
TXLS8REC.EQU
TWBkUTIL.INC
TWBkUTIL.CLW
TPicture.INC
TPicture.CLW
TOleStorage.INC
TOleStorage.CLW
TNativeExcel.DOC
TNativeExcelTutorial
.DOC
TnativeExcelDemo.A
PP

7\Accessory\Libsrc\W
in

%ROOT%\3rdparty\docs\
Taboga\TNativeExcel

%ROOT
%\3rdparty\examples\
Taboga\TNativeExcel
Note: %ROOT% is the root directory where Clarion 6 was installed.
this would be C:\Clarion6.

Typically

The above table is just a reference for your convenience. The installation script
takes care of setting everything in the proper place, and it also registers the
template.

Q U I C K S TA RT

The best way to become familiarized with the library is to look at the included
TNativeExcelDemo.APP application. This application includes all the examples from
the tutorial, and provides the fastest route to start using the library.
The tutorial is contained in the TNativeExcelTutorial.DOC document, also
included.
INCLUDING THE LIBRARY IN YOUR APPLICATION

The easiest way to include the library in your application is to use the global
extension TEnableNativeExcel included in the TNativeExcel template set.
This global extension will properly include all the required library files into your
application, and set up all the required compiler directives to properly include the
library in single EXE and multi-dll applications.
USING THE LIBRARY

Here is a short example which illustrates the most simple use of the library:
program
map
end
INCLUDE('TWorkbook.INC')

wBook

TWorkbook
CODE
wBook.Init()
wBook.TakeLabel('A1','Some text...')
wBook.TakeLabel(1,2,'Another text...')
wBook.TakeNumber(A2,45.5563)
wBook.Save(simple.xls)
wBook.Kill

!Initialize the library

!Write some text on cell A1
!Note cell address can also be given in Row,Col format.
!..Row=1, Col=2 is equivalent to reference B1
!Write a number on cell A2
!Omit filename and library will ask for one
!Finish up

How to use the Library

OVERVIEW ON COMMON USE OF THE LIBRARY

S O M E P R E L I M I N A RY C O N C E P T S
WORKBOOK IS BUILT IN MEMORY BEFORE WRITING TO DISK

A very important thing that should be understood before using the library is that
when you declare an object of the TWorkbook class, and start writing data and
formulas to the worksheet, and formatting it with different fonts, alignments, etc,
everything is being held in memory, and it is only until you save to disk that the
whole workbook is committed to disk.
There are some very important reasons and implications on why this is the case.
One very important reason/implication is that because of this, when you apply
formatting to a given cell, column or row, the formatting can and will override any
previous formatting on that same section.
This is similar to when you are working with Excel. If you specify a font to a
given cell for example -, and then you specify a different font for the column
on which the cell lies, the cell is reformatted to the column font (the last font
specified). In other words, the last format call remains.
When you are working with Excel this is rarely a source of problems because you
are visually overseeing the format changes; however, this is an area where caution
must be used on the Native Excel library because you will only see the final workbook
result.ing.
wBook.SetFont(Arial,10)
wBook.TakeLabel(A1,Example text)
wBook.ResetStyle()
...
...
...
wBook.SetFont(Arial,24)
wBook.TakeColumn(1,1)
wBook.ResetStyle()

!Set current font to Arial 10

!Write text to A1, for now using Arial 10
!Resets any formatting to default values...

!Set the font to Arial

!Apply the font to the
!..Text in cell A1 get
!Resets any formatting

24
FIRST column.
CHANGED to Arial 24...!!
to default values...

The above code shows the Last Format Applies principle we have been describing.
When the label in cell A1 was written, it was formatted using the font Arial 10.
However, further down, the whole first column (which contains the cell A1) was
formatted to use the font Arial 24.
At this moment, the cell A1 changed its
format to use Arial 24.
In our experience, this is the most common cause of getting unexpected results
when using the library. And extra caution must be taken when applying formatting to
rows or columns.

E N T E R I N G C E L L D ATA

Data is entered in the worksheet using one of the following library functions:
TakeLabel, TakeNumber, TakeInteger, TakeDate, and TakeTime. Depending on the
specific type of data you want to assign to a worksheet cell (i.e. label, number,
integer, date, or time) you choose the appropiate function.
TAKELABEL

In Excel, text strings are called labels; thus, when you want to write a text string
to a cell you use the TakeLabel function.
For example, the following function call writes the label Some Text string into
the cell A1 of the worksheet.
myWBookObj.TakeLabel(A1,Some Text string...)

TAKENUMBER AND TAKEINTEGER

In a similar fashion, the TakeNumber function writes a decimal or real value

into the given cell, and TakeInteger does the same but for an integer value.
TAKEDATE AND TAKETIME

These final two functions, as their name imply, are for writing dates and times
respectively.
REFERENCES AND ROW/COLUMN PAIRS

Each of the data entry functions have two versions: one that take references, and
one that takes Row/Column indexes.
Cell references are strings in the format column index as a letter, and row index
as number. Thus, the cell reference A1 refers to the first (A) column, and the first
(1) row. Below are some other examples of cell references.
Cell Reference
F45
AB32

Column
F = 6th column
AB = 26*1 + 2 = 28th column

Row
45th row
32nd row

MN4

GE = 26*7 + 5 = 187th column

4th row

Row/column indexes is where we actually specify the row and column pair. For
example 1,1 represent the first row, and the first column, 32,44 represent the 32nd
row and 44th column.
It is important to note that cell references are given in column/row order, whereas
row/column indexes are given in row/column order.
TWO VERSIONS OF EACH DATA ENTRY FUNCTION

Each one of the data entry functions (i.e. TakeLabel, TakeNumber, TakeInteger,
TakeDate, and Taketime) has two versions: one that uses cell references, and one
that uses row/column pairs.
Thus, for example, the following two function calls are equivalent:
myWBookObj.TakeNumber(B1,45.7)
myWBookObj.TakeNumber(1,2,45.7)

!Writes 45.7 into the cell on column B and row = 1

!..Same: writes 45.7 into cell on col. 2 and row = 1

F O R M ATT I N G

After data entry the most used functionality is cell, column and row formatting.
Hence, a very powerful feature of the Taboga Native Excel library is the flexibility in
formatting cells, rows and columns.
We must caution also, that formatting it is the most common cause of getting
unexpected results as we saw in the Preliminary Concepts section above .
APPLYING FORMATTING

In many ways, formatting in the TNativeExcel library is analogous to the way it

works when applying formatting in Excel:
You specify the desired formatting or style and then you apply it to a given
selection. For example, if you want to specify a particular font for a worksheet cell,
you first select the font, and then you enter the data in the cell.
The cell contents
will then display in the currently selected font.
It works in a similar fashion in the library.
write data to a given cell:

You first specify the font, and then

!Set the current font to Arial, size 10, blue in color, and BOLD+UNDERLINE...
wBook.SetFont('Arial', 10, COLOR:BLUE , FONT:BOLD+FONT:UNDERLINE)
!..Once the font is set, any data written will take on that font:
wBook.TakeLabel('A1','This text uses: Arial 10, Bold&Underline + Blue')
wBook.TakeLabel('A2','This ALSO uses the same font')
wBook.ResetStyle()
!Reset all formats to the default values...
wBook.TakeLabel('A3','This label however uses the NORMAL DEFAULT FONT')

ROWS AND COLUMNS

Formatting applied to a column or row will affect all cells contained in that row
or column. The library will in fact go through all the cells in the given row or column
and apply the new formatting.
This again works in a very similar way to MS Excel.
In Excel, if you aply any
formatting to a column or row, that formatting is also applied to all the cells in the
given row or column.
FONT FORMATTING

In the previous section we saw an example of how to apply font formatting to a

given cell. In addition to applying a font to a specific cell, you can apply a specific
font to a whole column or to a whole row.
In all cases the process is similar. You first set the specific font with the desired
properties as the current font, and then you either write a cell contents, or apply
the font to a column or row.
To set the current font, you use the SetFont method, which allows you to specify
the following font properties: Font name, font size, font color, font style, font charset,
font weight, underline style, and escapement type. All the parameters are optional
except the Font Name.
If a parameter is omitted, that parameters currently
selected value remains.
For example, if the current font Arial 16 bold, and you call SetFont(Garamond),
the current font will change to Garamond 16 bold. The size and font style bold will
remain, as these were omitted.
SOME NOTES ON SETTING FONT PROPERTIES

FontColor: If you choose to specify a font color, you can use any of the clarion
COLOR equates, or specify a particular color using standard Clarion color values.
Excel BIFF8 however, has a limit of 54 different colors on a workbook. The library
will thus adjust the palette of colors saved to the workbook according to the colors
used.
FontStyle: Again, the library will accept using clarion equates. Thus you can set
the style to FONT:BOLD+FONT:UNDERLINE, and the library will understand these
equates.
FontUnderline: If you specify the style as underline, you can then specify the
particular style of underline. To do this you can use one of the following equates:
xlsUnderline::Single
xlsUnderline::Double
xlsUnderline::SingleAccounting
xlsUnderline::DoubleAccounting

Single line underline

Double line underline
Single-line, accounting style
Double-line accounting style

EscapementStyle: This specifies whether the font is superscript or subscript.

specify, use one of the following equates:
xlsFont:::Superscript

Font is superscript

To

xlsFont:::Subscript

Font is subscript

FORMATTING SCOPE

The current formatting or style will remain in effect until it is reset to the default
values. For example, if you set a particular font, it becomes the current font. This
current font will be applied to all cells, columns and rows which are worked on while
it is selected:
wBook.SetFont('Arial', 10, COLOR:BLUE , FONT:BOLD+FONT:UNDERLINE)
!..Once the font is set, any data written will take on that font:
wBook.TakeLabel('A1','This text uses: Arial 10, Bold&Underline + Blue')
...
...
... At some other point in the code, we take another label.
The currently selected
... font is still the same.
...
wBook.TakeLabel('A2','This ALSO uses the same font')
...
...
wBook.TakeColumn(1,4) !The same font (Arial 10) is applied to columns 1 to 4...
...
...
wBook.ResetStyle()
!NOW all formatting is reset to default

Thus, when you are finished with a particular font, you should make sure to call
the method ResetFormat, to set all formatting to default.
An
alternative
to
the
TWorkbook.ResetFormat()
method,
is
TWorkbook.Style.Reset() method. Both methods exactly the same function.

the

HORIZONTAL AND VERTICAL ALIGNMENT FORMATTING

Horizontal alignment is set using the SetAlignment method, with the desired
horizontal alignment style as the passed parameter:
Horizontal Alignment Style
constant

Description

xls::ALIGN_GENERAL

Default alignment for the given cell

contents
Left align data
Center align data
Right align data
Fill all the cell with the cell contents
Justify the cell contents
Center across selection
Distributed alignment

xls::ALIGN_LEFT
xls::ALIGN_CENTER
xls::ALIGN_RIGHT
xls::ALIGN_FILLCELL
xls::ALIGN_JUSTIFIED
xls::ALIGN_CENTERACCROSSSELECTION
xls::ALIGN_DISTRIBUTED

Vertical alignment is set using the SetVerticalAlignment method, with the desired
verticla alignment style as the parameter:
Vertical Alignment Style
constant

Description

xls::VERT_ALIGN_TOP
xls::VERT_ALIGN_CENTERED

Default vertical alignment = top of cell

Verically align data at the center of the
cell

Vertically align data on the bottom of the

cell
Vertically justify the cell contents
Vertically distribute the cell contents

xls::VERT_ALIGN_BOTTOM
xls::VERT_ALIGN_JUSTIFIED
xls::VERT_ALIGN_DISTRIBUTED

APPLYING ALIGNMENT FORMAT

In accordance to all the formatting actions in the Native Excel library, you first set
the alignment, and then apply it to the cells, columns or rows:
wBook.SetAlignment(xls::ALIGN_RIGHT)

!Set horizontal alignment to RIGHT ALIGNED

wBook.TakeLabel('A1','This text will be right aligned')

...
wBook.TakeLabel('A3','This text will also be right aligned')
...
...
...
wBook.SetVerticalAlignment(xls::VERT_ALIGN_CENTERED) !Set vertical alignment to centered...
wBook.TakeLabel('A5','This will be right aligned AND centered on the cell...')
...
wBook.ResetStyle()
!Reset all formats (including alignment) to defaults

CELL PICTURES (FORMAT PICTURES)

As you probably know, you can specify a cell picture in Excel (though in Excel
these are called Cell Formats).
In the Native Excel library you can specify the cell format picture by calling the
SetFormatPicture method. The parameter is then the Cell format, or picture desired.
The interesting thing is that the library recognizes Clarion style pictures, so you
can specify the format picture in either Clarions format (e.g. @N-12.4, @D4, etc),
or Excels own format picture syntax.
The library will correctly interpret either
syntax.
STYLE STRUCTURE

There is an alternate way to specify the different formatting characteristics of

cells, columns and rows: using the Style structure of the workbook. In fact, all the
methods we have previously described for formatting the workbook contents
internally do just modify this Style structure.
The style structure is the group of fields where the currently active formatting
information is contained for the given cell, column or row.
Alternatively then, you can manipulate the current active format using this Style
structure (object) of the workbook. The code below sets various font properties in
this way using the Style structure.
!Set the current font to Arial, size 10, blue in color, and BOLD+UNDERLINE...
wBook.style.FontName = Arial'
wBook.style.FontSize = 10
wBook.style.FontColor = COLOR:BLUE
wBook.style.FontStyole FONT:BOLD+FONT:UNDERLINE)

!..Once the font is set, any data written will take on that font:
wBook.TakeLabel('A1','This text uses: Arial 10, Bold&Underline + Blue')
wBook.TakeLabel('A2','This ALSO uses the same font')
wBook.ResetStyle()
wBook.TakeLabel('A3','This label however uses the NORMAL DEFAULT FONT')

This also works for alignment, and all the properties defined in the Style structure.
The code beow is identical to the alignment example given above.
wBook.Style.HorizontalAlignment = xls::ALIGN_RIGHT

!Horizontal alignment to RIGHT ALIGNED

wBook.TakeLabel('A1','This text will be right aligned')

...
wBook.TakeLabel('A3','This text will also be right aligned')
...
...
...
wBook.Style.VerticalAlignment = xls::VERT_ALIGN_CENTERED !Vertical alignment to centered...
wBook.TakeLabel('A5','This will be right aligned AND centered on the cell...')
...
wBook.ResetStyle()
!Reset all formatting (including alignment) to defaults

It is very important to understand that any formatting (or style) which is applied
by altering the Style structure, remains in effect until you specifically reset it calling
either TWorkbook.ResetStyle(), or TWorkbook.Style.Reset().
Again, both of these method calls do exactly the same.
TWorkbook.ResetStyle() just call the Style.Reset() method internally.

In

fact,