Overview of Some Central Interfaces

BASIC Guide

{{{parttitle}}}

[[{{{PrevPart}}}|< Previous Section ]]

[[{{{NextPart}}}| Next Section >]]

• The Language of OpenOffice.org Basic

• Overview of a Basic Program
• Working With Variables
• Strings
• Numbers
• Boolean Values
• Date and Time
• Arrays
• Scope and Life Span of Variables
• Constants
• Operators
• Branching
• Loops
• Procedures and Functions
• Error Handling
• Other Instructions

• Runtime Library

• Conversion Functions
• Strings
• Date and Time
• Files and Directories
• Message and Input Boxes
• Other Functions

• Introduction to the API

• Universal Network Objects (UNO)
• Properties and Methods
• Modules, Services and Interfaces
• Tools for Working with UNO
• Overview of Central Interfaces

• Working with Documents

• The StarDesktop
• Styles and Templates

• Text Documents

• The Structure of Text Documents
• Editing Text Documents
• More than Just Text

• Spreadsheet Documents

• The Structure of Spreadsheets
  • Rows and Columns
  • Cells and Ranges
  • Formatting Spreadsheet Documents
• Editing Spreadsheet Documents

• Drawings and Presentations

• The Structure of Drawings
• Editing Drawing Objects
• Presentations

• Charts (Diagrams)

• Using Charts in Spreadsheets
• The Structure of Charts
• Chart Types

• Databases

• SQL: a Query Language
• Types of Database Access
• Data Sources
• Database Access

• Dialogs

• Working With Dialogs
• Properties
• Events
• Dialog Control Elements

• Forms

• Working With Forms
• Control Element Forms
• Database Forms

< Previous Page

Next Page >

Some interfaces of OpenOffice.org can be found in many parts of the OpenOffice.org API. They define sets of methods for abstract tasks which can be applied to various problems. Here, you will find an overview of the most common of these interfaces.

The origin of the objects is explained at a later point in this guide. At this point, only some of the abstract aspects of objects, for which the OpenOffice.org API provides some central interfaces, are discussed.

Creating Context-Dependent Objects

The OpenOffice.org API provides two options for creating objects. One can be found in the createUnoService function mentioned at the start of this chapter. createUnoService creates an object which can be used universally. Such objects and services are also known as context-independent services.

In addition to context-independent services, there are also context-dependent services whose objects are only useful when used in conjunction with another object. A drawing object for a spreadsheet document, for example, can therefore only exist in conjunction with this one document.

com.sun.star.lang.XMultiServiceFactory Interface

Context-dependent objects are usually created by means of an object method, on which the object depends. The createInstance method, which is defined in the XMultiServiceFactory interface, is used in particular in the document objects.

The drawing object can, for example, be created as follows using a spreadsheet object:

Dim RectangleShape As Object
RectangleShape = _
  Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")

A paragraph template in a text document is created in the same way:

Dim Style as Object
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")

Named Access to Subordinate Objects

The XNameAccess and XNameContainer interfaces are used in objects that contain subordinate objects, which can be addressed using a natural language name.

While XNameAccess permits access to the individual objects, XNameContainer takes on the insertion, modification and deletion of elements.

com.sun.star.container.XNameAccess Interface

An example of the use of XNameAccess is provided by the sheets object of a spreadsheet. It combines all the pages within the spreadsheet. The individual pages are accessed from the sheets object, by using the getByName method from XNameAccess:

Dim Sheets As Object
Dim Sheet As Object

Sheets = Spreadsheet.Sheets
Sheet = Sheets.getByName("Sheet1")

The getElementNames method provides an overview of the names of all elements. As a result, it returns a data field containing the names. The following example shows how all element names of a spreadsheet can thereby be determined and displayed in a loop:

Dim Sheets As Object
Dim SheetNames
Dim I As Integer

Sheets = Spreadsheet.Sheets
SheetNames = Sheets.getElementNames

For I=LBound(SheetNames) To UBound(SheetNames)
  MsgBox SheetNames(I)
Next I

The hasByName method of the XNameAccess interface reveals whether a subordinate object with a particular name exists within the basic object. The following example therefore displays a message that informs the user whether the Spreadsheet object contains a page of the name Sheet1.

Dim Sheets As Object

Sheets = Spreadsheet.Sheets
If Sheets.HasByName("Sheet1") Then
  MsgBox " Sheet1 available"
Else
  MsgBox "Sheet1 not available"
End If

com.sun.star.container.XNameContainer Interface

The XNameContainer interface takes on the insertion, deletion and modification of subordinate elements in a basic object. The functions responsible are insertByName, removeByName and replaceByName.

The following is a practical example of this. It calls a text document, which contains a StyleFamilies object and uses this to in turn make the paragraph templates (ParagraphStyles) of the document available.

Dim StyleFamilies As Object
Dim ParagraphStyles As Object
Dim NewStyle As Object   

StyleFamilies = Textdoc.StyleFamilies
ParagraphStyles = StyleFamilies.getByName("ParagraphStyles")
ParagraphStyles.insertByName("NewStyle", NewStyle)      
ParagraphStyles.replaceByName("ChangingStyle", NewStyle)   
ParagraphStyles.removeByName("OldStyle")

The insertByName line inserts the NewStyle style under the name of the same name in the ParagraphStyles object. The replaceByName line changes the object behind ChangingStyle into NewStyle. Finally, the removeByName call removes the object behind OldStyle from ParagraphStyles.

Index-Based Access to Subordinate Objects

The XIndexAccess and XIndexContainer interfaces are used in objects which contain subordinate objects and which can be addressed using an index.

XIndexAccess provides the methods for accessing individual objects. XIndexContainer provides methods for inserting and removing elements.

com.sun.star.container.XIndexAccess Interface

XIndexAccess provides the getByIndex and getCount methods for calling the subordinate objects. getByIndex provides an object with a particular index. getCount returns how many objects are available.

Dim Sheets As Object
Dim Sheet As Object
Dim I As Integer

Sheets = Spreadsheet.Sheets

For I = 0 to Sheets.getCount() - 1
  Sheet = Sheets.getByIndex(I)
  ' Editing sheet
Next I

The example shows a loop that runs through all sheet elements one after another and saves a reference to each in the Sheet object variable. When working with the indexes, note that getCount returns the number of elements. The elements in getByIndex however are numbered beginning with 0. The counting variable of the loop therefore runs from 0 to getCount()-1.

com.sun.star.container.XIndexContainer Interface

The XIndexContainer interface provides the insertByIndex and removeByIndex functions. The parameters are structured in the same way as the corresponding functions in XNameContainer.

Iterative Access to Subordinate Objects

In some instances, an object may contain a list of subordinate objects that cannot be addressed by either a name or an index. In these situations, the XEnumeration and XenumerationAccess interfaces are appropriate. They provide a mechanism through which all subordinate elements of an objects can be passed, step by step, without having to use direct addressing.

com.sun.star.container.XEnumeration and XenumerationAccess Interfaces

The basic object must provide the XEnumerationAccess interface, which contains only a createEnumeration method. This returns an auxiliary object, which in turn provides the XEnumeration interface with the hasMoreElements and nextElement methods. Through these, you then have access to the subordinate objects.

The following example steps through all the paragraphs of a text:

Dim ParagraphEnumeration As Object
Dim Paragraph As Object

ParagraphEnumeration = Textdoc.Text.createEnumeration

While ParagraphEnumeration.hasMoreElements()
  Paragraph = ParagraphEnumeration.nextElement()
Wend

The example first creates a ParagraphEnumeration auxiliary object. This gradually returns the individual paragraphs of the text in a loop. The loop is terminated as soon as the hasMoreElements method returns the False value, signaling that the end of the text has been reached. fr:FR/Documentation/BASIC Guide/Interface Overview hu:HU/Documentation/BASIC Guide/Interface Overview it:IT/Documentation/BASIC Guide/Interface Overview ja:JA/Documentation/BASIC Guide/Interface Overview zh:ZH/Documentation/BASIC Guide/Interface Overview

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