Xbasic

Performing Common Excel Spreadsheet Operations

IN THIS PAGE

Basics
Creating and Managing Workbooks and Spreadsheets
Understanding spreadsheet addressing and formulas
Getting and setting values
Clear all or part of a spreadsheet
Free a document from memory
Run Excel on a saved document
Database operations
Intermediate Tasks
Add a formula to a spreadsheet cell
Working with Pictures
Working with sheets
Formats and Fonts
Advanced Topics
Working with existing spreadsheets
Working with ranges and groups
Insert or remove rows or columns
Load or save a work book from a memory image (blob)
Adjust printing properties

Description

This page includes basic, intermediate, and advanced points on performing spreadsheet operations, from getting and setting simple values to adjusting printer properties.

Basics

Creating and Managing Workbooks and Spreadsheets

Create a new in-memory document (work book), for an Excel 2007 spreadsheet.
```
dim Doc as Office::ExcelDocument
```
or for an Excel 2003 spreadsheet
```
dim Doc as Office::Excel2003Document
```
Create a new spreadsheet
```
dim Sheet as Office::Spreadsheet
```
Attach a sheet to a document (work book)
```
Sheet = Doc.AddSheet("My sheet name")
```

Add a string to a spreadsheet cell

dim row as N = 1 
dim column as N = 1 
dim message as C = "Hello, World!" 
Sheet.Write(row, column, message)

Sheet.Write(row, column, message, Format)

Understanding spreadsheet addressing and formulas
The APIs in the Office class address cells by row and then column number. Excel and compatible sheets call the columns A, B, C, ... (up to 16,384 columns) and the rows 1, 2, 3, ... (up to 1,048,576 rows) and give the column before the row. When you are writing (row, column) in an API call, both row and column must be integer numbers. When you are writing a cell reference in a formula, use numbers for the row and letters for the column, e.g. B3 for column 2, row 3. Use a '$' symbol to indicate that a row or column in a reference is relative rather than absolute, e.g. $B$3 for the cell 2 columns to the right and 3 columns down. Formulas start with '=' and may include operators between cells and sheet designations followed by a '!'. So "=Sheet2!C6-Sheet3!E15" means to subtract the value of row 15 column 5 in Sheet3 from the value of row 6 column 3 in Sheet2.

Getting and setting values

Add a number to a spreadsheet cell

dim number as N = 3.1415926
Sheet.Write(row, column, number)

Sheet.Write(row, column, number, Format)

Get cell type

dim ct as Office::CellType = Sheet.CellType(row, column)

Read cell format

dim cf as Office::CellFormat = Sheet.CellFormat(row, column)

Read cell contents. Note that Sheet.Read returns an A (Any) type variable

if ct <> Office::CellType::Error 
    contents = Sheet.Read(row, column) 
end if

Read cell contents and format

if ct <> Office::CellType::Error 
    Contents = Sheet.Read(row, column, ct) 
end if

Read cell comment

dim comment as C
comment = Sheet.ReadComment(row, column)

Read cell formula

dim formula as C 
if Sheet.IsFormula(row, column) 
    formula = Sheet.ReadFormula(row, column) 
end if

Check cell for specific attributes

dim answer as L answer = Sheet.IsBlank(row, column)
answer = Sheet.IsBlank(row, column, cf) 
answer = Sheet.IsFormula(row, column) 
answer = Sheet.CellIsDateValue(row, column)

Copy a cell

Sheet.CopyCell(sourceRow, sourceColumn, destinationRow, destinationColumn)

Blank a cell without changing the format
```
Sheet.SetBlank(row, column)
```
Blank a cell and change the format
```
Sheet.SetBlank(row, column, cf)
```

Clear all or part of a spreadsheet
- ```
Sheet.Clear()
Sheet.Clear(FirstRow, FirstColumn, LastRow, LastColumn)
```
- Save a document (work book)
```
Doc.Save(filename)
```
- Reinitialize an in-memory document (work book)
```
Doc.Clear()
```
Free a document from memory
```
delete Doc
```
Run Excel on a saved document
```
sys_open(filename)
```

Database operations

Create a spreadsheet from a DBF

on error goto noload 
    myTable = table.open(Path + TableName + ".DBF")
    Sheet = Doc.AddSheetFromDBF(myTable, TableName) 
    
    'more processing of sheet... 
    '... 
noload: 
    ' continue...

Create a spreadsheet from a SQL Query

dim cn as sql::connection 
if cn.Open(ConnectionString) 
    if cn.Execute(Query) 
        Sheet = Doc.AddSheetFromResultSet(cn.ResultSet, mySheetName) 
        'More processing... 
        '... 
    end if 
end if

Intermediate Tasks

Add a formula to a spreadsheet cell

dim formula as C = "=B2+C3"
Sheet.WriteFormula(row, column, formula)

Sheet.WriteFormula(row, column, formula, Format)

Working with Pictures

Add a picture to a spreadsheet cell

dim picfile as C = "Daffodils.jpg"
dim picBlob as B
dim Id as N
Id = Doc.AddPicture(picfile)

picBlob = File.To_Blob(picfile)
Id = Doc.AddPicture(picBlob)

then

Sheet = Doc.AddSheet("Picture")
Sheet.SetPicture(row, column,Id)

Working with sheets

Copy a sheet

Doc.CopySheet(newSheetName, oldSheetIndex)

Delete a sheet
```
Doc.DeleteSheet(Index)
```
Count sheets in a workbook
```
nSheets = Doc.SheetCount
```
Get a spreadsheet by name
```
Doc.FindSheet(Sheet,sheetName)
```
Get a spreadsheet at an index number
```
Sheet = Doc.GetSheet(Index)
```
Split a sheet
```
Sheet.Split(row, column)
```

Formats and Fonts

Basics

dim Format as Office::Format
dim Font as Office::Font
Format = Doc.AddFormat()
Font = Doc.AddFont()
Font.Color = Office::Color::DarkBlue 
Font.Name= "Tahoma" 
Font.Size = 14 
Font.Bold = .t. 
Format.Font = Font 
Format.HorizontalAlignment = Office::HorizontalAlignment::Center

Count Fonts
```
nFonts = Doc.FontCount
```
Get a Font
```
font1 = Doc.GetFont(Index)
```
Count Formats
```
nFonts = Doc.FormatCount
```
Get a Format
```
format1 = Doc.GetFormat(Index)
```

Apply a Format to a spreadsheet cell or region

Sheet.SetFormat(row, column, format) 
Sheet.SetFormat(startRow, startColumn, endRow, endColumn, format)

Get/set the height/width of a row/column

Width = Sheet.ColumnWidth(column) 
Height = Sheet.RowHeight(row) 
Sheet.SetColumn(FirstColumn, LastColumn, Width [, Format [, Hidden]]) 
Sheet.SetColumn(row, Height [, Format [, Hidden]])

Add an entry in the next available row of a sheet

nextRow = Sheet.NextAvailableRow
Sheet.Write(nextRow, 1, "More text")

Advanced Topics

Working with existing spreadsheets

Load the contents of an existing Excel file

dim filename as C = "myworkbook.xlsx" 
dim result as L = Doc.Load(filename)

Open a spreadsheet file, select a sheet, write to a location, and save

dim filename as C = "myworkbook.xlsx" 
if Doc.Load(filename) 
    if Doc.FindSheet(Sheet,sheetName) 
        Sheet.Write(row, column, contents) 
        Doc.Save(filename) 
    end if 
end if

Working with ranges and groups

Merge a cell range (erasing the cell boundary lines)

Sheet.SetMerge(FirstRow, LastRow, FirstColumn, LastColumn)

Get merged cell range to which a cell belongs

Sheet.GetMerge(row, column, FirstRow, LastRow, FirstColumn, LastColumn)

Delete (unmerge) a merged cell range
```
Sheet.DeleteMerge(row, column)
```
Group rows and collapse the group
```
Sheet.GroupRows(FirstRow, LastRow, .T.)
```

Group columns and collapse the group

Sheet.GroupColumns(FirstColumn, LastColumn, .T.)

Insert or remove rows or columns

Sheet.InsertRow(FirstRow, LastRow) 
Sheet.InsertColumn(FirstColum, LastColum) 
Sheet.RemoveRow(FirstRow, LastRow) 
Sheet.RemoveColumn(FirstColum, LastColum)

Load or save a work book from a memory image (blob)

dim Data as B 
Doc.SaveToBlob(Data) 
Doc.LoadFromBlob(Data)

Adjust printing properties

Adjust spreadsheet margins

Sheet.HeaderMargin = 10 
Sheet.FooterMargin = 10 
Sheet.MarginLeft = 10 
Sheet.MarginRight = 10 
Sheet.MarginTop = 10 
Sheet.MarginBottom = 10

Set spreadsheet orientation and centering

Sheet.Landscape = .T. 
Sheet.CenterHorizontally = .T. 
Sheet.CenterVertically = .F.

Set paper size
```
Sheet.Paper = Office::Paper::Legal
```
Create page break at a row
```
Sheet.SetHorizontalPageBreak(row, .T.)
```
Remove page break at a row
```
Sheet.SetHorizontalPageBreak(row, .F.)
```
Create page break at a column
```
Sheet.SetVerticalPageBreak(column, .T.)
```
Remove page break at a column
```
Sheet.SetVerticalPageBreak(column, .F.)
```