Difference between revisions of "Documentation/BASIC Guide/Interface Overview"

From Apache OpenOffice Wiki
Jump to: navigation, search
m
 
(10 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Overview of Some Central Interfaces}}
 
 
{{Documentation/BASICGuideTOC/v2
 
{{Documentation/BASICGuideTOC/v2
 
|ShowPrevNext=block
 
|ShowPrevNext=block
Line 7: Line 6:
 
|api=block
 
|api=block
 
}}
 
}}
 +
{{DISPLAYTITLE:Overview of Some Central Interfaces}}
 +
__NOTOC__
 +
Some interfaces of {{AOo}} can be found in many parts of the {{AOo}} 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.
  
Some interfaces of {{OOo}} can be found in many parts of the {{OOo}} 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 abstract aspects of objects, for which the {{AOo}} API provides some central interfaces, are discussed.
 
 
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 {{OOo}} API provides some central interfaces, are discussed.
 
  
 
== Creating Context-Dependent Objects ==
 
== Creating Context-Dependent Objects ==
  
The {{OOo}} API provides two options for creating objects. One can be found in the <tt>createUnoService</tt> function mentioned at the start of this chapter. <tt>createUnoService</tt> creates an object which can be used universally. Such objects and services are also known as context-independent services.  
+
The {{AOo}} API provides two options for creating objects. One can be found in the <tt>createUnoService</tt> function mentioned at the start of this chapter. <tt>createUnoService</tt> 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.
 
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.
Line 24: Line 24:
 
The drawing object can, for example, be created as follows using a spreadsheet object:  
 
The drawing object can, for example, be created as follows using a spreadsheet object:  
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim RectangleShape As Object
 
Dim RectangleShape As Object
 
RectangleShape = _
 
RectangleShape = _
 
   Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")
 
   Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")
</source>
+
</syntaxhighlight>
  
 
A paragraph template in a text document is created in the same way:  
 
A paragraph template in a text document is created in the same way:  
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Style as Object
 
Dim Style as Object
 
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")
 
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")
</source>
+
</syntaxhighlight>
  
 
== Named Access to Subordinate Objects ==
 
== Named Access to Subordinate Objects ==
Line 41: Line 41:
 
The <tt>XNameAccess</tt> and <tt>XNameContainer</tt> interfaces are used in objects that contain subordinate objects, which can be addressed using a natural language name.  
 
The <tt>XNameAccess</tt> and <tt>XNameContainer</tt> interfaces are used in objects that contain subordinate objects, which can be addressed using a natural language name.  
  
While <tt>XNamedAccess</tt> permits access to the individual objects, <tt>XNameContainer</tt> takes on the insertion, modification and deletion of elements.
+
While <tt>XNameAccess</tt> permits access to the individual objects, <tt>XNameContainer</tt> takes on the insertion, modification and deletion of elements.
  
 
=== <tt>com.sun.star.container.XNameAccess</tt> Interface ===
 
=== <tt>com.sun.star.container.XNameAccess</tt> Interface ===
  
An example of the use of <tt>XNameAccess</tt> is provided by the sheet object of a spreadsheet. It combines all the pages within the spreadsheet. The individual pages are accessed using the <tt>getByName</tt> method from <tt>XNameAccess</tt>:  
+
An example of the use of <tt>XNameAccess</tt> is provided by the <tt>sheets</tt> object of a spreadsheet. It combines all the pages within the spreadsheet. The individual pages are accessed from the <tt>sheets</tt> object, by using the <tt>getByName</tt> method from <tt>XNameAccess</tt>:  
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Sheets As Object
 
Dim Sheets As Object
 
Dim Sheet As Object
 
Dim Sheet As Object
Line 53: Line 53:
 
Sheets = Spreadsheet.Sheets
 
Sheets = Spreadsheet.Sheets
 
Sheet = Sheets.getByName("Sheet1")
 
Sheet = Sheets.getByName("Sheet1")
</source>
+
</syntaxhighlight>
  
 
The <tt>getElementNames</tt> 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:  
 
The <tt>getElementNames</tt> 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:  
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Sheets As Object
 
Dim Sheets As Object
 
Dim SheetNames
 
Dim SheetNames
Line 68: Line 68:
 
   MsgBox SheetNames(I)
 
   MsgBox SheetNames(I)
 
Next I
 
Next I
</source>
+
</syntaxhighlight>
  
 
The <tt>hasByName</tt> method of the <tt>XNameAccess</tt> 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 <tt>Spreadsheet</tt> object contains a page of the name <tt>Sheet1</tt>.
 
The <tt>hasByName</tt> method of the <tt>XNameAccess</tt> 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 <tt>Spreadsheet</tt> object contains a page of the name <tt>Sheet1</tt>.
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Sheets As Object
 
Dim Sheets As Object
  
Line 81: Line 81:
 
   MsgBox "Sheet1 not available"
 
   MsgBox "Sheet1 not available"
 
End If
 
End If
</source>
+
</syntaxhighlight>
  
 
=== <tt>com.sun.star.container.XNameContainer</tt> Interface ===
 
=== <tt>com.sun.star.container.XNameContainer</tt> Interface ===
Line 89: Line 89:
 
The following is a practical example of this. It calls a text document, which contains a <tt>StyleFamilies</tt> object and uses this to in turn make the paragraph templates (ParagraphStyles) of the document available.  
 
The following is a practical example of this. It calls a text document, which contains a <tt>StyleFamilies</tt> object and uses this to in turn make the paragraph templates (ParagraphStyles) of the document available.  
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim StyleFamilies As Object
 
Dim StyleFamilies As Object
 
Dim ParagraphStyles As Object
 
Dim ParagraphStyles As Object
Line 99: Line 99:
 
ParagraphStyles.replaceByName("ChangingStyle", NewStyle)   
 
ParagraphStyles.replaceByName("ChangingStyle", NewStyle)   
 
ParagraphStyles.removeByName("OldStyle")             
 
ParagraphStyles.removeByName("OldStyle")             
</source>
+
</syntaxhighlight>
  
 
The <tt>insertByName</tt> line inserts the <tt>NewStyle</tt> style under the name of the same name in the <tt>ParagraphStyles</tt> object. The <tt>replaceByName</tt> line changes the object behind <tt>ChangingStyle</tt> into <tt>NewStyle</tt>. Finally, the <tt>removeByName</tt> call removes the object behind <tt>OldStyle</tt> from <tt>ParagraphStyles</tt>.
 
The <tt>insertByName</tt> line inserts the <tt>NewStyle</tt> style under the name of the same name in the <tt>ParagraphStyles</tt> object. The <tt>replaceByName</tt> line changes the object behind <tt>ChangingStyle</tt> into <tt>NewStyle</tt>. Finally, the <tt>removeByName</tt> call removes the object behind <tt>OldStyle</tt> from <tt>ParagraphStyles</tt>.
Line 113: Line 113:
 
<tt>XIndexAccess</tt> provides the <tt>getByIndex</tt> and <tt>getCount</tt> methods for calling the subordinate objects. <tt>getByIndex</tt> provides an object with a particular index. <tt>getCount</tt> returns how many objects are available.  
 
<tt>XIndexAccess</tt> provides the <tt>getByIndex</tt> and <tt>getCount</tt> methods for calling the subordinate objects. <tt>getByIndex</tt> provides an object with a particular index. <tt>getCount</tt> returns how many objects are available.  
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim Sheets As Object
 
Dim Sheets As Object
 
Dim Sheet As Object
 
Dim Sheet As Object
Line 124: Line 124:
 
   ' Editing sheet
 
   ' Editing sheet
 
Next I
 
Next I
</source>
+
</syntaxhighlight>
  
 
The example shows a loop that runs through all sheet elements one after another and saves a reference to each in the <tt>Sheet</tt> object variable. When working with the indexes, note that <tt>getCount</tt> returns the number of elements. The elements in <tt>getByIndex</tt> however are numbered beginning with 0. The counting variable of the loop therefore runs from 0 to <tt>getCount()-1</tt>.
 
The example shows a loop that runs through all sheet elements one after another and saves a reference to each in the <tt>Sheet</tt> object variable. When working with the indexes, note that <tt>getCount</tt> returns the number of elements. The elements in <tt>getByIndex</tt> however are numbered beginning with 0. The counting variable of the loop therefore runs from 0 to <tt>getCount()-1</tt>.
Line 142: Line 142:
 
The following example steps through all the paragraphs of a text:
 
The following example steps through all the paragraphs of a text:
  
<source lang="oobas">
+
<syntaxhighlight lang="oobas">
 
Dim ParagraphEnumeration As Object
 
Dim ParagraphEnumeration As Object
 
Dim Paragraph As Object
 
Dim Paragraph As Object
Line 151: Line 151:
 
   Paragraph = ParagraphEnumeration.nextElement()
 
   Paragraph = ParagraphEnumeration.nextElement()
 
Wend
 
Wend
</source>
+
</syntaxhighlight>
  
 
The example first creates a <tt>ParagraphEnumeration</tt> auxiliary object. This gradually returns the individual paragraphs of the text in a loop. The loop is terminated as soon as the <tt>hasMoreElements</tt> method returns the <tt>False</tt> value, signaling that the end of the text has been reached.
 
The example first creates a <tt>ParagraphEnumeration</tt> auxiliary object. This gradually returns the individual paragraphs of the text in a loop. The loop is terminated as soon as the <tt>hasMoreElements</tt> method returns the <tt>False</tt> value, signaling that the end of the text has been reached.
  
 +
 +
{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Interface Overview}}
 
{{PDL1}}
 
{{PDL1}}

Latest revision as of 12:19, 30 January 2021


Some interfaces of Apache OpenOffice can be found in many parts of the Apache OpenOffice 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 abstract aspects of objects, for which the Apache OpenOffice API provides some central interfaces, are discussed.

Creating Context-Dependent Objects

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


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



Personal tools