Difference between revisions of "Documentation/BASIC Guide/Interface Overview"
m |
|||
(10 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | |||
{{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. | ||
− | + | 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 | ||
== Creating Context-Dependent Objects == | == Creating Context-Dependent Objects == | ||
− | The {{ | + | 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: | ||
− | < | + | <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") | ||
− | </ | + | </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: | ||
− | < | + | <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") | ||
− | </ | + | </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> | + | 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 | + | 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>: |
− | < | + | <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") | ||
− | </ | + | </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: | ||
− | < | + | <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 | ||
− | </ | + | </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>. | ||
− | < | + | <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 | ||
− | </ | + | </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. | ||
− | < | + | <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") | ||
− | </ | + | </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. | ||
− | < | + | <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 | ||
− | </ | + | </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: | ||
− | < | + | <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 | ||
− | </ | + | </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). |