Sun and OracleChannel SunHow to BuyLog In한국어

StarOffice 8 Programming Guide for BASIC
검색에만이 책은
검색 도움말
이 책의 내용보기:
Contained Within
Find More Documentation
Featured Support Resources
 PDF로 이 문서 다운로드 (1223 KB)

Chapter 7 Spreadsheet Documents

StarOffice Basic provides an extensive interface for program-controlled creation and editing of spreadsheets. This chapter describes how to control the relevant services, methods and properties of spreadsheet documents.

The first section addresses the basic structure of spreadsheet documents and shows you how to access and to edit the contents of individual cells.

The second section concentrates on how to edit spreadsheets efficiently by focusing on cell areas and the options for searching and replacing cell contents.

Note –

The Range object allows you to address any table area and has been extended in the new API.

The Structure of Table-Based Documents (Spreadsheets)

The document object of a spreadsheet is based on the com.sun.star.sheet.SpreadsheetDocument service. Each of these documents may contain several spreadsheets. In this guide, a table-based document or spreadsheet document is the entire document, whereas a spreadsheet (or sheet for short) is a sheet (table) in the document.

Note –

Different terminology for spreadsheets and their content is used in VBA and StarOffice Basic. Whereas the document object in VBA is called a Workbook and its individual pages Worksheets , they are called SpreadsheetDocument and Sheet in StarOffice Basic.

Spreadsheets

You can access the individual sheets of a spreadsheet document through the Sheets list.

The following examples show you how to access a sheet either through its number or its name.

Example 1: access by means of the number (numbering begins with 0) 

Dim Doc As Object
Dim Sheet As Object

Doc = StarDesktop.CurrentComponent
Sheet  = Doc. Sheets (0)

Example 2: access by means of the name 

Dim Doc As Object
Dim Sheet As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets.getByName("Sheet 1")

In the first example, the sheet is accessed by its number (counting begins at 0). In the second example, the sheet is accessed by its name and the getByName method.

The Sheet object that is obtained by the getByName method supports the com.sun.star.sheet.Spreadsheet service. In addition to providing several interfaces for editing the content, this service provides the following properties:

  • IsVisible (Boolean) – the spreadsheet is visible.

  • PageStyle (String) – name of the page template for the spreadsheet.

Creating, Deleting and Renaming Sheets

The Sheets list for a spreadsheet document is also used to create, delete, and rename individual sheets. The following example uses the hasByName method to check if a sheet called MySheet exists. If it does, the method determines a corresponding object reference by using the getByName method and then saves the reference in a variable in Sheet. If the corresponding sheet does not exist, it is created by the createInstance call and inserted in the spreadsheet document by the insertByName method.

Dim Doc As Object
Dim Sheet As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

If Doc.Sheets.hasByName("MySheet") Then
   Sheet = Doc.Sheets.getByName("MySheet")
Else
   Sheet = Doc.createInstance("com.sun.star.sheet.Spreadsheet")
   Doc.Sheets.insertByName("MySheet", Sheet)
End If

The getByName and insertByName methods are from the com.sun.star.container.XnameContainer interface as described in Chapter 4, Introduction to the StarOffice API.

Rows and Columns

Each sheet contains a list of its rows and columns. These are available through the Rows and Columns properties of the spreadsheet object and support the com.sun.star.table.TableColumns and/or com.sun.star.table.TableRows services.

The following example creates two objects that reference the first row and the first column of a sheet and stores the references in the FirstCol and FirstRow object variables.

Dim Doc As Object
Dim Sheet As Object
Dim FirstRow As Object
Dim FirstCol As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

FirstCol = Sheet.Columns(0)
FirstRow = Sheet.Rows(0)

The column objects support the com.sun.star.table.TableColumn service that has the following properties:

  • Width (long) – width of a column in hundredths of a millimeter.

  • OptimalWidth (Boolean) – sets a column to its optimum width.

  • IsVisible (Boolean) – displays a column.

  • IsStartOfNewPage (Boolean) – when printing, creates a page break before a column.

The width of a column is only optimized when the OptimalWidth property is set to True. If the width of an individual cell is changed, the width of the column that contains the cell is not changed. In terms of functionality, OptimalWidth is more of a method than a property.

The row objects are based on the com.sun.star.table.RowColumn service that has the following properties:

  • Height (long) - height of the row in 100ths of a millimeter.

  • OptimalHeight (Boolean) - sets the row to its optimum height.

  • IsVisible (Boolean) - displays the row.

  • IsStartOfNewPage (Boolean) - when printing, creates a page break before the row.

If the OptimalHeight property of a row is set to the True, the row height changes automatically when the height of a cell in the row is changed. Automatic optimization continues until the row is assigned an absolute height through the Height property.

The following example activates the automatic height optimization for the first five rows in the sheet and makes the second column invisible.

Dim Doc As Object
Dim Sheet As Object
Dim Row As Object
Dim Col As Object
Dim I As Integer

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

For I = 0 To 4
   Row = Sheet.Rows(I)
   Row.OptimalHeight = True
Next I

Col = Sheet.Columns(1)
Col.IsVisible = False
Note –

The Rows and Columns lists can be accessed through an index in StarOffice Basic. Unlike in VBA, the first column has the index 0 and not the index 1.

Inserting and Deleting Rows and Columns

The Rows and Columns objects of a sheet can access existing rows and columns as well as insert and delete them.

Dim Doc As Object
Dim Sheet As Object
Dim NewColumn As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

Sheet.Columns.insertByIndex(3, 1)
Sheet.Columns.removeByIndex(5, 1)

This example uses the insertByIndex method to insert a new column into the fourth column position in the sheet (index 3 - numbering starts at 0). The second parameter specifies the number of columns to be inserted (in this example: one).

The removeByIndex method deletes the sixth column (index 5). Again, the second parameter specifies the number of columns that you want to delete.

The methods for inserting and deleting rows use the Rows object function in the same way as the methods shown for editing columns using the Columns object.

Cells

A spreadsheet consists of a two-dimensional list containing cells. Each cell is defined by its X and Y-position with respect to the top left cell which has the position (0,0).

The following example creates an object that references the top left cell and inserts a text in the cell:

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object   

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

Cell = Sheet.getCellByPosition(0, 0)
Cell.String = "Test"

In addition to numerical coordinates, each cell in a sheet has a name, for example, the top left cell (0,0) of a spreadsheet is called A1. The letter A stands for the column and the number 1 for the row. It is important that the name and position of a cell are not confused because row counting for names begins with 1 but the counting for position begins with 0.

In StarOffice, a table cell can be empty or contain text, numbers, or formulas. The cell type is not determined by the content that is saved in the cell, but rather the object property which was used for its entry. Numbers can be inserted and called up with the Value property, text with the String property, and formulas with the Formula property.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object   

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

Cell = Sheet.getCellByPosition(0, 0)
Cell.Value = 100

Cell = Sheet.getCellByPosition(0, 1)
Cell.String = "Test"

Cell = Sheet.getCellByPosition(0, 2)
Cell.Formula = "=A1"

The example inserts one number, one text, and one formula in the fields A1 to A3.

Note –

The Value, String, and Formula properties supersede the PutCell method for setting the values of a table cell.

StarOffice treats cell content that is entered using the String property as text, even if the content is a number. Numbers are left-aligned in the cell instead of right-aligned. You should also note the difference between text and numbers when you use formulas:

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

Cell = Sheet.getCellByPosition(0, 0)
Cell.Value = 100

Cell = Sheet.getCellByPosition(0, 1)
Cell.String = 1000

Cell = Sheet.getCellByPosition(0, 2)
Cell.Formula = "=A1+A2"

MsgBox Cell.Value

Although cell A1 contains the value 100 and cell A2 contains the value 1000, the A1+A2 formula returns the value 100. This is because the contents of cell A2 were entered as a string and not as a number.

To check if the contents of a cell contains a number or a string, use the Type property:

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)

Cell.Value = 1000

Select Case Cell.Type 
Case com.sun.star.table.CellContentType.EMPTY 
   MsgBox "Content: Empty"
Case com.sun.star.table.CellContentType.VALUE
   MsgBox "Content: Value"
Case com.sun.star.table.CellContentType.TEXT
   MsgBox "Content: Text"
Case com.sun.star.table.CellContentType.FORMULA
   MsgBox "Content: Formula"
End Select

The Cell.Type property returns a value for the com.sun.star.table.CellContentType enumeration which identifies the contents type of a cell. The possible values are:

  • EMPTY - no value

  • VALUE - number

  • TEXT - strings

  • FORMULA - formula

Inserting, Deleting, Copying and Moving Cells

In addition to directly modifying cell content, StarOffice Calc also provides an interface that allows you to insert, delete, copy, or merge cells. The interface (com.sun.star.sheet.XRangeMovement) is available through the spreadsheet object and provides four methods for modifying cell content.

The insertCell method is used to insert cells into a sheet.

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2

Sheet.insertCells(CellRangeAddress, com.sun.star.sheet.CellInsertMode.DOWN)

This example inserts a cells range that is two rows by two columns in size into the second column and row (each bear the number 1) of the first sheet (number 0) in the spreadsheet. Any existing values in the specified cell range are moved below the range.

To define the cell range that you want to insert, use the com.sun.star.table.CellRangeAddress structure. The following values are included in this structure:

  • Sheet (short) - number of the sheet (numbering begins with 0).

  • StartColumn (long) – first column in the cell range (numbering begins with 0).

  • StartRow (long) – first row in the cell range (numbering begins with 0).

  • EndColumn (long) – final column in the cell range (numbering begins with 0).

  • EndRow (long) – final row in the cell range (numbering begins with 0).

The completed CellRangeAddress structure must be passed as the first parameter to the insertCells method. The second parameter of insertCells contains a value of the com.sun.star.sheet.CellInsertMode enumeration and defines what is to be done with the values that are located in front of the insert position. The CellInsertMode enumeration recognizes the following values:

  • NONE – the current values remain in their present position.

  • DOWN – the cells at and under the insert position are moved downwards.

  • RIGHT – the cells at and to the right of the insert position are moved to the right.

  • ROWS – the rows after the insert position are moved downwards.

  • COLUMNS – the columns after the insert position are moved to the right.

The removeRange method is the counterpart to the insertCells method. This method deletes the range that is defined in the CellRangeAddress structure from the sheet.

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2

Sheet.removeRange(CellRangeAddress, com.sun.star.sheet.CellDeleteMode.UP)

This example removes the B2:C3 cell range from the sheet and then shifts the underlying cells up by two rows. The type of removal is defined by one of the following values from the com.sun.star.sheet.CellDeleteMode enumeration:

  • NONE – the current values remain in their current position.

  • UP – the cells at and below the insert position are moved upwards.

  • LEFT – the cells at and to the right of the insert position are moved to the left.

  • ROWS – the rows after the insert position are moved upwards.

  • COLUMNS – the columns after the insert position are moved to the left.

The XRangeMovement interface provides two additional methods for moving (moveRange) or copying (copyRange) cell ranges. The following example moves the B2:C3 range so that the range starts at position A6:

Dim Doc As Object
Dim Sheet As Object
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress
Dim CellAddress As New com.sun.star.table.CellAddress

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

CellRangeAddress.Sheet = 0
CellRangeAddress.StartColumn = 1
CellRangeAddress.StartRow = 1
CellRangeAddress.EndColumn = 2
CellRangeAddress.EndRow = 2

CellAddress.Sheet = 0
CellAddress.Column = 0
CellAddress.Row = 5

Sheet.moveRange(CellAddress, CellRangeAddress)

In addition to the CellRangeAdress structure, the moveRange method expects a com.sun.star.table.CellAddress structure to define the origin of the move's target region. The CellAddress method provides the following values:

  • Sheet (short) – number of the spreadsheet (numbering begins with 0).

  • Column (long) – number of the addressed column (numbering begins with 0).

  • Row (long) – number of the addressed row (numbering begins with 0).

The cell contents in the target range are always overwritten by the moveRange method. Unlike in the InsertCells method , a parameter for performing automatic moves is not provided in the removeRange method.

The copyRange method functions in the same way as the moveRange method, except that copyRange inserts a copy of the cell range instead of moving it.

Note –

In terms of their function, the StarOffice Basic insertCell, removeRange, and copyRange methods are comparable with the VBA Range.Insert, Range.Delete ,and Range.Copy methods. Whereas in VBA, the methods are applied to the corresponding Range object, in StarOffice Basic they are applied to the associated Sheet object.

Formatting

A spreadsheet document provides properties and methods for formatting cells and pages.

Cell Properties

There are numerous options for formatting cells, such as specifying the font type and size for text. Each cell supports the com.sun.star.style.CharacterProperties and com.sun.star.style.ParagraphProperties services, the main properties of which are described in Chapter 6, Text Documents. Special cell formatting is handled by the com.sun.star.table.CellProperties service. The main properties of this service are described in the following sections.

You can apply all of the named properties to individual cells and to cell ranges.

Note –

The CellProperties object in the StarOffice API is comparable with the Interior object from VBA which also defines cell-specific properties.

Background Color and Shadows

The com.sun.star.table.CellProperties service provides the following properties for defining background colors and shadows:

  • CellBackColor (Long) – background color of the table cell.

  • IsCellBackgroundTransparent (Boolean) – sets the background color to transparent.

  • ShadowFormat (struct) – specifies the shadow for cells (structure in accordance with com.sun.star.table.ShadowFormat ).

The com.sun.star.table.ShadowFormat structure and the detailed specifications for cell shadows have the following structure:

  • Location (enum) – position of shadow (value from the com.sun.star.table.ShadowLocation structure).

  • ShadowWidth (Short) – size of shadow in hundredths of a millimeter.

  • IsTransparent (Boolean) – sets the shadow to transparent.

  • Color (Long) – color of shadow.

The following example writes the number 1000 to the B2 cell, changes the background color to red using the CellBackColor property, and then creates a light gray shadow for the cell that is moved 1 mm to the left and down.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object
Dim ShadowFormat As New com.sun.star.table.ShadowFormat

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)

Cell.Value = 1000

Cell.CellBackColor = RGB(255, 0, 0)

ShadowFormat.Location = com.sun.star.table.ShadowLocation.BOTTOM_RIGHT
ShadowFormat.ShadowWidth = 100
ShadowFormat.Color = RGB(160, 160, 160)

Cell.ShadowFormat = ShadowFormat

Justification

StarOffice provides various functions that allow you to change the justification of a text in a table cell.

The following properties define the horizontal and vertical justification of a text:

  • HoriJustify (enum) – horizontal justification of the text (value from com.sun.star.table.CellHoriJustify)

  • VertJustify (enum) - vertical justification of the text (value from com.sun.star.table.CellVertJustify)

  • Orientation (enum) – orientation of text (value in accordance with com.sun.star.table.CellOrientation)

  • IsTextWrapped (Boolean) – permits automatic line breaks within the cell

  • RotateAngle (Long) – angle of rotation of text in hundredths of a degree

The following example shows how you can "stack" the contents of a cell so that the individual characters are printed one under another in the top left corner of the cell. The characters are not rotated.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)

Cell.Value = 1000

Cell.HoriJustify = com.sun.star.table.CellHoriJustify.LEFT
Cell.VertJustify = com.sun.star.table.CellVertJustify.TOP
Cell.Orientation = com.sun.star.table.CellOrientation.STACKED

Number, Date and Text Format

StarOffice provides a whole range of predefined date and time formats. Each of these formats has an internal number that is used to assign the format to cells using the NumberFormat property. StarOffice provides the queryKey and addNew methods so that you can access existing number formats as well as create your own number formats. The methods are accessed through the following object call:

NumberFormats = Doc.NumberFormats

A format is specified using a format string that is structured in a similar way to the format function of StarOffice Basic. However there is one major difference: whereas the command format expects English abbreviations and decimal points or characters as thousands separators, the country-specified abbreviations must be used for the structure of a command format for the NumberFormats object.

The following example formats the B2 cell so that numbers are displayed with three decimal places and use commas as a thousands separator.

Dim Doc As Object
Dim Sheet As Object
Dim Cell As Object
Dim NumberFormats As Object
Dim NumberFormatString As String
Dim NumberFormatId As Long
Dim LocalSettings As New com.sun.star.lang.Locale

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
Cell = Sheet.getCellByPosition(1,1)

Cell.Value = 23400.3523565

LocalSettings.Language = "en"
LocalSettings.Country = "us"

NumberFormats = Doc.NumberFormats
NumberFormatString = "#,##0.000"

NumberFormatId = NumberFormats.queryKey(NumberFormatString, LocalSettings, True)
If NumberFormatId = -1 Then
   NumberFormatId = NumberFormats.addNew(NumberFormatString, LocalSettings)
End If

MsgBox NumberFormatId
Cell.NumberFormat = NumberFormatId

The Format Cells dialog in StarOffice Calc provides an overview of the different formatting options for cells.

Page Properties

Page properties are the formatting options that position document content on a page as well as visual elements that are repeated page after page. These include

  • Paper formats

  • Page margins

  • Headers and footers.

The procedure for defining page formats differs from other forms of formatting. Whereas cell, paragraph, and character element can be directly, page formats can also be defined and indirectly applied using page styles. For example, headers or footers are added to the page style.

The following sections describe the main formatting options for spreadsheet pages. Many of the styles that are described are also available for text documents. The page properties that are valid for both types of documents are defined in the com.sun.star.style.PageProperties service. The page properties that only apply to spreadsheet documents are defined in the com.sun.star.sheet.TablePageStyle service.

Note –

The page properties (page margins, borders, and so on) for a Microsoft Office document are defined by means of a PageSetup object at the Worksheet object (Excel) or Document object (Word) level. In StarOffice, these properties are defined using a page style which in turn is linked to the associated document.

Page Background

The com.sun.star.style.PageProperties service defines the following properties of a pages background:

  • BackColor (long) – color of background

  • BackGraphicURL (String) – URL of the background graphics that you want to use

  • BackGraphicFilter (String) – name of the filter for interpreting the background graphics

  • BackGraphicLocation (Enum) – position of the background graphics (value according to enumeration)

  • BackTransparent (Boolean) - makes the background transparent

Page Format

The page format is defined using the following properties of the com.sun.star.style.PageProperties service:

  • IsLandscape (Boolean) – landscape format

  • Width (long) – width of page in hundredths of a millimeter

  • Height (long) – height of page in hundredths of a millimeter

  • PrinterPaperTray (String) – name of the printer paper tray that you want to use

The following example sets the page size of the "Default" page style to the DIN A5 landscape format (height 14.8 cm, width 21 cm):

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object 
Dim PageStyles As Object
Dim DefPage As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
PageStyles = StyleFamilies.getByName("PageStyles")
DefPage = PageStyles.getByName("Default")

DefPage.IsLandscape = True
DefPage.Width = 21000
DefPage.Height = 14800

Page Margin, Border, and Shadow

The com.sun.star.style.PageProperties service provides the following properties for adjusting page margins as well as borders and shadows:

  • LeftMargin (long) – width of the left hand page margin in hundredths of a millimeter

  • RightMargin (long) – width of the right hand page margin in hundredths of a millimeter.

  • TopMargin (long) – width of the top page margin in hundredths of a millimeter

  • BottomMargin (long) – width of the bottom page margin in hundredths of a millimeter

  • LeftBorder (struct) – specifications for left-hand line of page border (com.sun.star.table.BorderLine structure)

  • RightBorder (struct) – specifications for right-hand line of page border ((com.sun.star.table.BorderLine structure)

  • TopBorder (struct) – specifications for top line of page border ((com.sun.star.table.BorderLine structure)

  • BottomBorder (struct) – specifications for bottom line of page border ((com.sun.star.table.BorderLine structure)

  • LeftBorderDistance (long) – distance between left-hand page border and page content in hundredths of a millimeter

  • RightBorderDistance (long) – distance between right-hand page border and page content in hundredths of a millimeter

  • TopBorderDistance (long) – distance between top page border and page content in hundredths of a millimeter

  • BottomBorderDistance (long) – distance between bottom page border and page content in hundredths of a millimeter

  • ShadowFormat (struct) – specifications for shadow of content area of page ((com.sun.star.table.ShadowFormat structure)

The following example sets the left and right-hand borders of the "Default" page style to 1 centimeter.

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object 
Dim PageStyles As Object
Dim DefPage As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
PageStyles = StyleFamilies.getByName("PageStyles")
DefPage = PageStyles.getByName("Default")

DefPage.LeftMargin = 1000
DefPage.RightMargin = 1000

Headers and Footers

The headers and footers of a document form part of the page properties and are defined using the com.sun.star.style.PageProperties service. The properties for formatting headers are:

  • HeaderIsOn (Boolean) – header is activated

  • HeaderLeftMargin (long) – distance between header and left-hand page margin in hundredths of a millimeter.

  • HeaderRightMargin (long) – distance between header and right-hand page margin in hundredths of a millimeter

  • HeaderBodyDistance (long) – distance between header and main body of document in hundredths of a millimeter

  • HeaderHeight (long) – height of header in hundredths of a millimeter

  • HeaderIsDynamicHeight (Boolean) – height of header is automatically adapted to content

  • HeaderLeftBorder (struct) – details of the left-hand border of frame around header (com.sun.star.table.BorderLine structure)

  • HeaderRightBorder (struct) – details of the right-hand border of frame around header (com.sun.star.table.BorderLine structure)

  • HeaderTopBorder (struct) – details of the top line of the border around header (com.sun.star.table.BorderLine structure)

  • HeaderBottomBorder (struct) – details of the bottom line of the border around header (com.sun.star.table.BorderLine structure)

  • HeaderLeftBorderDistance (long) – distance between left-hand border and content of header in hundredths of a millimeter

  • HeaderRightBorderDistance (long) – distance between right-hand border and content of header in hundredths of a millimeter

  • HeaderTopBorderDistance (long) – distance between top border and content of header in hundredths of a millimeter

  • HeaderBottomBorderDistance (long) – distance between bottom border and content of header in hundredths of a millimeter

  • HeaderIsShared (Boolean) – headers on even and odd pages have the same content (refer to HeaderText , HeaderTextLeft, and HeaderTextRight )

  • HeaderBackColor (long) – background color of header

  • HeaderBackGraphicURL (String) – URL of the background graphics that you want to use

  • HeaderBackGraphicFilter (String) – name of the filter for interpreting the background graphics for the header

  • HeaderBackGraphicLocation (Enum) – position of the background graphics for the header (value according to com.sun.star.style.GraphicLocation enumeration)

  • HeaderBackTransparent (Boolean) – shows the background of the header as transparent

  • HeaderShadowFormat (struct) – details of shadow of header (com.sun.star.table.ShadowFormat structure)

The properties for formatting footers are:

  • FooterIsOn (Boolean) – footer is activated

  • FooterLeftMargin (long) – distance between footer and left-hand page margin in hundredths of a millimeter

  • FooterRightMargin (long) – distance between footer and right-hand page margin in hundredths of a millimeter

  • FooterBodyDistance (long) – distance between footer and main body of document in hundredths of a millimeter

  • FooterHeight (long) – height of footer in hundredths of a millimeter

  • FooterIsDynamicHeight (Boolean) – height of footer is adapted automatically to the content

  • FooterLeftBorder (struct) – details of left-hand line of border around footer (com.sun.star.table.BorderLine structure)

  • FooterRightBorder (struct) – details of right-hand line of border around footer (com.sun.star.table.BorderLine structure)

  • FooterTopBorder (struct) – details of top line of border around footer (com.sun.star.table.BorderLine structure)

  • FooterBottomBorder (struct) – details of bottom line of border around footer (com.sun.star.table.BorderLine structure)

  • FooterLeftBorderDistance (long) – distance between left-hand border and content of footer in hundredths of a millimeter

  • FooterRightBorderDistance (long) – distance between right-hand border and content of footer in hundredths of a millimeter

  • FooterTopBorderDistance (long) – distance between top border and content of footer in hundredths of a millimeter

  • FooterBottomBorderDistance (long) – distance between bottom border and content of footer in hundredths of a millimeter

  • FooterIsShared (Boolean) – the footers on the even and odd pages have the same content (refer to FooterText, FooterTextLeft, and FooterTextRight ).

  • FooterBackColor (long) – background color of footer

  • FooterBackGraphicURL (String) – URL of the background graphics that you want to use

  • FooterBackGraphicFilter (String) – name of the filter for interpreting the background graphics for the footer

  • FooterBackGraphicLocation (Enum) – position of background graphics for the footer (value according to com.sun.star.style.GraphicLocation enumeration)

  • FooterBackTransparent (Boolean) – shows the background of the footer as transparent

  • FooterShadowFormat (struct) – details of shadow of footer (com.sun.star.table.ShadowFormat structure)

Changing the Text of Headers and Footers

The content of headers and footers in a spreadsheet is accessed through the following properties:

  • LeftPageHeaderContent (Object) - content of headers for even pages (com.sun.star.sheet.HeaderFooterContent service)

  • RightPageHeaderContent (Object) - content of headers for odd pages (com.sun.star.sheet.HeaderFooterContent service)

  • LeftPageFooterContent (Object)- content of footers for even pages (com.sun.star.sheet.HeaderFooterContent service)

  • RightPageFooterContent (Object) - content of footers for odd pages (com.sun.star.sheet.HeaderFooterContent service)

If you do not need to distinguish between headers or footers for odd and even pages (the FooterIsShared property is False), then set the properties for headers and footers on odd pages.

All the named objects return an object that supports the com.sun.star.sheet.HeaderFooterContent service. By means of the (non-genuine) properties LeftText, CenterText, and RightText, this service provides three text elements for the headers and footers of StarOffice Calc.

The following example writes the "Just a Test." value in the left-hand text field of the header from the "Default" template.

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object 
Dim PageStyles As Object
Dim DefPage As Object
Dim HText As Object
Dim HContent As Object
Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
PageStyles = StyleFamilies.getByName("PageStyles")
DefPage = PageStyles.getByName("Default")

DefPage.HeaderIsOn = True
HContent = DefPage.RightPageHeaderContent
HText = HContent.LeftText
HText.String = "Just a Test."
DefPage.RightPageHeaderContent = HContent

Note the last line in the example: Once the text is changed, the TextContent object must be assigned to the header again so that the change is effective.

Another mechanism for changing the text of headers and footers is available for text documents (StarOffice Writer) because these consist of a single block of text. The following properties are defined in the com.sun.star.style.PageProperties service:

  • HeaderText (Object) – text object with content of the header (com.sun.star.text.XText service)

  • HeaderTextLeft (Object) – text object with content of headers on left-hand pages (com.sun.star.text.XText service)

  • HeaderTextRight (Object) – text object with content of headers on right-hand pages (com.sun.star.text.XText service)

  • FooterText (Object) – text object with content of the footer (com.sun.star.text.XText service)

  • FooterTextLeft (Object) – text object with content of footers on left-hand pages (com.sun.star.text.XText service)

  • FooterTextRight (Object) – text object with content of footers on right-hand pages (com.sun.star.text.XText service)

The following example creates a header in the "Default" page style for text documents and adds the text "Just a Test" to the header.

Dim Doc As Object
Dim Sheet As Object
Dim StyleFamilies As Object 
Dim PageStyles As Object
Dim DefPage As Object
Dim HText As Object

Doc = StarDesktop.CurrentComponent
StyleFamilies = Doc.StyleFamilies
PageStyles = StyleFamilies.getByName("PageStyles")
DefPage = PageStyles.getByName("Default")

DefPage.HeaderIsOn = True
HText = DefPage.HeaderText 

HText.String = "Just a Test."

In this instance, access is provided directly through the HeaderText property of the page style rather than the HeaderFooterContent object.

Centering (Spreadsheets Only)

The com.sun.star.sheet.TablePageStyle service is only used in StarOffice Calc page styles and allows cell ranges that you want to printed to be centered on the page. This service provides the following properties:

  • CenterHorizontally (Boolean) - table content is centered horizontally

  • CenterVertically (Boolean) - table content is centered vertically

Definition of Elements to be Printed (Spreadsheets Only)

When you format sheets, you can define whether page elements are visible. For this purpose, the com.sun.star.sheet.TablePageStyle service provides the following properties:

  • PrintAnnotations (Boolean) - prints cell comments

  • PrintGrid (Boolean) - prints the cell gridlines

  • PrintHeaders (Boolean) - prints the row and column headings

  • PrintCharts (Boolean) - prints charts contained in a sheet

  • PrintObjects (Boolean) - prints embedded objects

  • PrintDrawing (Boolean) - prints draw objects

  • PrintDownFirst (Boolean) - if the contents of a sheet extend across several pages, they are first printed in vertically descending order, and then down the right-hand side.

  • PrintFormulas (Boolean) - prints the formulas instead of the calculated values

  • PrintZeroValues (Boolean)- prints the zero values

Editing Spreadsheet Documents Efficiently

Whereas the previous section described the main structure of spreadsheet documents, this section describes the services that allow you to easily access individual cells or cell ranges.

Cell Ranges

In addition to an object for individual cells (com.sun.star.table.Cell service), StarOffice also provides objects that represent cell ranges. Such CellRange objects are created using the getCellRangeByName call of the spreadsheet object:

Dim Doc As Object
Dim Sheet As Object
Dim CellRange As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets.getByName("Sheet 1")
CellRange = Sheet.getCellRangeByName("A1:C15")

A colon (:) is used to specify a cell range in a spreadsheet document. For example, A1:C15 represents all the cells in rows 1 to 15 in columns A, B, and C.

The location of individual cells in a cell range can be determined using the getCellByPosition method, where the coordinates of the top left cell in the cell range is (0, 0). The following example uses this method to create an object of cell C3.

Dim Doc As Object
Dim Sheet As Object
Dim CellRange As Object
Dim Cell As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets.getByName("Sheet 1")
CellRange = Sheet.getCellRangeByName("B2:D4")
Cell = CellRange.GetCellByPosition(1, 1)

Formatting Cell Ranges

Just like individual cells, you can apply formatting to cell ranges using the com.sun.star.table.CellProperties service. For more information and examples of this service, see the Formatting section.

Computing With Cell Ranges

You can use the computeFunction method to perform mathematical operations on cell ranges. The computeFunction expects a constant as the parameter that describes the mathematical function that you want to use. The associated constants are defined in the com.sun.star.sheet.GeneralFunction enumeration. The following values are available:

  • SUM - sum of all numerical values

  • COUNT - total number of all values (including non-numerical values)

  • COUNTNUMS - total number of all numerical values

  • AVERAGE - average of all numerical values

  • MAX - largest numerical value

  • MIN - smallest numerical value

  • PRODUCT - product of all numerical values

  • STDEV - standard deviation

  • VAR - variance

  • STDEVP - standard deviation based on the total population

  • VARP - variance based on the total population

The following example computes the average value of the A1:C3 range and prints the result in a message box:

Dim Doc As Object
Dim Sheet As Object
Dim CellRange As Object

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets.getByName("Sheet 1")
CellRange = Sheet.getCellRangeByName("A1:C3")

MsgBox CellRange.computeFunction(com.sun.star.sheet.GeneralFunction.AVERAGE)

Deleting Cell Contents

The clearContents method simplifies the process of deleting cell contents and cell ranges in that it deletes one specific type of content from a cell range.

The following example removes all the strings and the direct formatting information from the B2:C3 range.

Dim Doc As Object
Dim Sheet As Object
Dim CellRange As Object
Dim Flags As Long

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)
CellRange = Sheet.getCellRangeByName("B2:C3")

Flags = com.sun.star.sheet.CellFlags.STRING + _
      com.sun.star.sheet.CellFlags.HARDATTR

CellRange.clearContents(Flags)

The flags specified in clearContents come from the com.sun.star.sheet.CellFlags constants list. This list provides the following elements:

  • VALUE - numerical values that are not formatted as date or time

  • DATETIME - numerical values that are formatted as date or time

  • STRING - strings

  • ANNOTATION - comments that are linked to cells

  • FORMULA - formulas

  • HARDATTR - direct formatting of cells

  • STYLES - indirect formatting

  • OBJECTS - drawing objects that are connected to cells

  • EDITATTR - character formatting that only applies to parts of the cells

You can also add the constants together to delete different information using a call from clearContents.

Searching and Replacing Cell Contents

Spreadsheet documents, like text documents, provide a function for searching and replacing.

The descriptor objects for searching and replacing in spreadsheet documents are not created directly through the document object, but rather through the Sheets list. The following is an example of a search and replace process:

Dim Doc As Object
Dim Sheet As Object
Dim ReplaceDescriptor As Object
Dim I As Integer

Doc = StarDesktop.CurrentComponent
Sheet = Doc.Sheets(0)

ReplaceDescriptor = Sheet.createReplaceDescriptor()
ReplaceDescriptor.SearchString = "is"
ReplaceDescriptor.ReplaceString = "was"
For I = 0 to Doc.Sheets.Count - 1
   Sheet = Doc.Sheets(I)
   Sheet.ReplaceAll(ReplaceDescriptor) 
Next I

This example uses the first page of the document to create a ReplaceDescriptor and then applies this to all pages in a loop.