Difference between revisions of "Documentation/BASIC Guide/Structure of Spreadsheets"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Cells)
(Cell Properties)
Line 335: Line 335:
 
=== Cell Properties ===
 
=== Cell Properties ===
  
There are numerous options for formatting cells, such as specifying the font type and size for text. Each cell supports the <tt>com.sun.star.style.CharacterProperties</tt> and <tt>com.sun.star.style.ParagraphProperties</tt> services, the main properties of which are described in [html/p19.html Chapter 6, Text Documents]. Special cell formatting is handled by the <tt>com.sun.star.table.CellProperties</tt> service. The main properties of this service are described in the following sections.
+
There are numerous options for formatting cells, such as specifying the font type and size for text. Each cell supports the <tt>com.sun.star.style.CharacterProperties</tt> and <tt>com.sun.star.style.ParagraphProperties</tt> services, the main properties of which are described in '''[[Documentation/BASIC Guide/Text Documents|Text Documents]]'''. Special cell formatting is handled by the <tt>com.sun.star.table.CellProperties</tt> 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.
 
You can apply all of the named properties to individual cells and to cell ranges.

Revision as of 08:36, 5 October 2007


The Structure of Spreadsheet Documents

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.

Template:Documentation/Note

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 Introduction to the 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


Template:Documentation/Note

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 Apache OpenOffice, 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.

Template:Documentation/Note

Apache OpenOffice 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, Apache OpenOffice 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.


Template:Documentation/Note

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 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.


Template:Documentation/Note

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

Apache OpenOffice 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

Apache OpenOffice 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. Apache OpenOffice 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 Apache OpenOffice 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 Apache OpenOffice 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.


Template:Documentation/Note

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 Apache OpenOffice 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 (Apache OpenOffice 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 Apache OpenOffice 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


Content on this page is licensed under the Public Documentation License (PDL).
Personal tools