Sancho at 11:35, 2 September 2011

2011-09-02T11:35:17Z

Sancho: Основной текст

2011-09-02T11:34:51Z

Основной текст

New page

<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Overview of Some Central Interfaces<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}

{{Documentation/BASICGuideTOC
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=EN/documentation/basic_guide/uno_tools
|NextPage=EN/documentation/basic_guide/documents
|api=block
}}

__NOTOC__

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 of the abstract aspects of objects, for which the {{OOo}} API provides some central interfaces, are discussed.

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

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.

=== <tt>com.sun.star.lang.XMultiServiceFactory</tt> Interface ===

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

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

<source lang="oobas">
Dim RectangleShape As Object
RectangleShape = _
Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")
</source>

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

<source lang="oobas">
Dim Style as Object
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")
</source>

== Named Access to Subordinate Objects ==

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

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">
Dim Sheets As Object
Dim Sheet As Object

Sheets = Spreadsheet.Sheets
Sheet = Sheets.getByName("Sheet1")
</source>

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">
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
</source>

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">
Dim Sheets As Object

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

=== <tt>com.sun.star.container.XNameContainer</tt> Interface ===

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

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">
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")
</source>

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

== Index-Based Access to Subordinate Objects ==

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

<tt>XIndexAccess</tt> provides the methods for accessing individual objects. <tt>XIndexContainer</tt> provides methods for inserting and removing elements.

=== <tt>com.sun.star.container.XIndexAccess</tt> Interface ===

<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">
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
</source>

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

=== <tt>com.sun.star.container.XIndexContainer</tt> Interface ===

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

== 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 <tt>XEnumeration</tt> and <tt>XenumerationAccess</tt> 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.

=== <tt>com.sun.star.container.XEnumeration</tt> and <tt>XenumerationAccess</tt> Interfaces ===

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

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

<source lang="oobas">
Dim ParagraphEnumeration As Object
Dim Paragraph As Object

ParagraphEnumeration = Textdoc.Text.createEnumeration

While ParagraphEnumeration.hasMoreElements()
Paragraph = ParagraphEnumeration.nextElement()
Wend
</source>

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.

{{PDL1}}

@@ Line 1: / Line 1: @@
 <section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Overview of Some Central Interfaces<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}
 {{Documentation/BASICGuideTOC
@@ Line 9: / Line 8: @@
 |api=block
 }}
 __NOTOC__
 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.

EN/documentation/basic guide/interface overview - Revision history

Sancho at 11:35, 2 September 2011

Sancho: Основной текст