Difference between revisions of "Documentation/DevGuide/FirstSteps/Element Access"
m |
|||
(13 intermediate revisions by 6 users not shown) | |||
Line 5: | Line 5: | ||
|NextPage=Documentation/DevGuide/FirstSteps/How do I know Which Type I Have? | |NextPage=Documentation/DevGuide/FirstSteps/How do I know Which Type I Have? | ||
}} | }} | ||
− | + | {{Documentation/DevGuideLanguages|Documentation/DevGuide/FirstSteps/{{SUBPAGENAME}}}} | |
{{DISPLAYTITLE:Element Access}} | {{DISPLAYTITLE:Element Access}} | ||
− | We have already seen in section [[Documentation/DevGuide/FirstSteps/How to get Objects in OpenOffice.org|How to get Objects in | + | We have already seen in the section [[Documentation/DevGuide/FirstSteps/How to get Objects in OpenOffice.org|How to get Objects in {{AOo}}]] that sets of objects can also be provided through element access methods. The three most important kinds of element access interfaces are <idl>com.sun.star.container.XNameContainer</idl>, <idl>com.sun.star.container.XIndexContainer</idl> and <idl>com.sun.star.container.XEnumeration</idl>. |
− | The three element access interfaces are examples of how the fine-grained interfaces of the {{ | + | The three element access interfaces are examples of how the fine-grained interfaces of the {{AOo}} API allow consistent object design. |
− | All three interfaces inherit from <code>XElementAccess</code> | + | All three interfaces inherit from <code>XElementAccess</code>; therefore, they include the methods |
− | + | <syntaxhighlight lang="java"> | |
type getElementType() | type getElementType() | ||
boolean hasElements() | boolean hasElements() | ||
− | + | </syntaxhighlight> | |
− | + | for finding out basic information about a set of elements. The method <code>hasElements()</code> tells whether or not a set contains any elements at all; the method <code>getElementType()</code> tells which type a set contains. In Java and C++, you can get information about a UNO type through <code>com.sun.star.uno.Type</code>, cf, the Java UNO and the C++ UNO reference. | |
The <idl>com.sun.star.container.XIndexContainer</idl> and <idl>com.sun.star.container.XNameContainer</idl> interface have a parallel design. Consider both interfaces in UML notation. | The <idl>com.sun.star.container.XIndexContainer</idl> and <idl>com.sun.star.container.XNameContainer</idl> interface have a parallel design. Consider both interfaces in UML notation. | ||
Line 41: | Line 41: | ||
The basic interface which hands out elements by name is the <idl>com.sun.star.container.XNameAccess</idl> interface. It has three methods: | The basic interface which hands out elements by name is the <idl>com.sun.star.container.XNameAccess</idl> interface. It has three methods: | ||
− | + | <syntaxhighlight lang="java"> | |
any getByName( [in] string name) | any getByName( [in] string name) | ||
sequence< string > getElementNames() | sequence< string > getElementNames() | ||
boolean hasByName( [in] string name) | boolean hasByName( [in] string name) | ||
− | + | </syntaxhighlight> | |
− | In the FirstLoadComponent example above, the method <code>getSheets()</code> returned a <idl>com.sun.star.sheet.XSpreadsheets</idl> interface, which inherits from <code>XNameAccess</code>. Therefore, you could use <code>getByName()</code> to obtain the sheet "MySheet" by name from the <code>XSpreadsheets</code> container: | + | In the FirstLoadComponent.java example above, the method <code>getSheets()</code> returned a <idl>com.sun.star.sheet.XSpreadsheets</idl> interface, which inherits from <code>XNameAccess</code>. Therefore, you could use <code>getByName()</code> to obtain the sheet "MySheet" by name from the <code>XSpreadsheets</code> container: |
− | + | <syntaxhighlight lang="java"> | |
XSpreadsheets xSpreadsheets = xSpreadsheetDocument.getSheets(); | XSpreadsheets xSpreadsheets = xSpreadsheetDocument.getSheets(); | ||
Line 58: | Line 58: | ||
// use XSpreadsheet interface to get the cell A1 at position 0,0 and enter 42 as value | // use XSpreadsheet interface to get the cell A1 at position 0,0 and enter 42 as value | ||
XCell xCell = xSpreadsheet.getCellByPosition(0, 0); | XCell xCell = xSpreadsheet.getCellByPosition(0, 0); | ||
− | + | </syntaxhighlight> | |
− | Since <code>getByName()</code> returns an any, you have to use <code>AnyConverter.toObject()</code> and/or <code>UnoRuntime.queryInterface()< | + | Since <code>getByName()</code> returns an any, you have to use <code>AnyConverter.toObject()</code> and/or <code>UnoRuntime.queryInterface()</code> before you can call methods at the spreadsheet object. |
===Index Access=== | ===Index Access=== | ||
The interface which hands out elements by index is the <idl>com.sun.star.container.XIndexAccess</idl> interface. It has two methods: | The interface which hands out elements by index is the <idl>com.sun.star.container.XIndexAccess</idl> interface. It has two methods: | ||
− | + | <syntaxhighlight lang="java"> | |
any getByIndex( [in] long index) | any getByIndex( [in] long index) | ||
long getCount() | long getCount() | ||
− | + | </syntaxhighlight> | |
The FirstLoadComponent example allows to demonstrate <code>XIndexAccess</code>. The API reference tells us that the service returned by <code>getSheets()</code> is a <idl>com.sun.star.sheet.Spreadsheet</idl> service and supports not only the interface <idl>com.sun.star.sheet.XSpreadsheets</idl>, but <code>XIndexAccess</code> as well. Therefore, the sheets could have been accessed by index and not just by name by performing a query for the <code>XIndexAccess</code> interface from our <code>xSpreadsheets</code> variable: | The FirstLoadComponent example allows to demonstrate <code>XIndexAccess</code>. The API reference tells us that the service returned by <code>getSheets()</code> is a <idl>com.sun.star.sheet.Spreadsheet</idl> service and supports not only the interface <idl>com.sun.star.sheet.XSpreadsheets</idl>, but <code>XIndexAccess</code> as well. Therefore, the sheets could have been accessed by index and not just by name by performing a query for the <code>XIndexAccess</code> interface from our <code>xSpreadsheets</code> variable: | ||
− | + | <syntaxhighlight lang="java"> | |
XIndexAccess xSheetIndexAccess = (XIndexAccess)UnoRuntime.queryInterface( | XIndexAccess xSheetIndexAccess = (XIndexAccess)UnoRuntime.queryInterface( | ||
XIndexAccess.class, xSpreadsheets); | XIndexAccess.class, xSpreadsheets); | ||
Object sheet = XSheetIndexAccess.getByIndex(0); | Object sheet = XSheetIndexAccess.getByIndex(0); | ||
− | + | </syntaxhighlight> | |
===Enumeration Access=== | ===Enumeration Access=== | ||
The interface <idl>com.sun.star.container.XEnumerationAccess</idl> creates enumerations that allow traveling across a set of objects. It has one method: | The interface <idl>com.sun.star.container.XEnumerationAccess</idl> creates enumerations that allow traveling across a set of objects. It has one method: | ||
− | + | <syntaxhighlight lang="java"> | |
com.sun.star.container.XEnumeration createEnumeration() | com.sun.star.container.XEnumeration createEnumeration() | ||
− | + | </syntaxhighlight> | |
The enumeration object gained from <code>createEnumeration()</code> supports the interface <idl>com.sun.star.container.XEnumeration</idl>. With this interface we can keep pulling elements out of the enumeration as long as it has more elements. <code>XEnumeration</code> supplies the methods: | The enumeration object gained from <code>createEnumeration()</code> supports the interface <idl>com.sun.star.container.XEnumeration</idl>. With this interface we can keep pulling elements out of the enumeration as long as it has more elements. <code>XEnumeration</code> supplies the methods: | ||
− | + | <syntaxhighlight lang="java"> | |
− | + | boolean hasMoreElements() | |
any nextElement() | any nextElement() | ||
− | + | </syntaxhighlight> | |
which are meant to build loops such as: | which are meant to build loops such as: | ||
− | + | <syntaxhighlight lang="java"> | |
while (xCells.hasMoreElements()) { | while (xCells.hasMoreElements()) { | ||
Line 101: | Line 101: | ||
// do something with cell | // do something with cell | ||
} | } | ||
− | + | </syntaxhighlight> | |
For example, in spreadsheets you have the opportunity to find out which cells contain formulas. The resulting set of cells is provided as <code>XEnumerationAccess</code>. | For example, in spreadsheets you have the opportunity to find out which cells contain formulas. The resulting set of cells is provided as <code>XEnumerationAccess</code>. | ||
Line 107: | Line 107: | ||
The interface that queries for cells with formulas is <idl>com.sun.star.sheet.XCellRangesQuery</idl>, it defines (among others) a method | The interface that queries for cells with formulas is <idl>com.sun.star.sheet.XCellRangesQuery</idl>, it defines (among others) a method | ||
− | + | <syntaxhighlight lang="java"> | |
XSheetCellRanges queryContentCells(short cellFlags) | XSheetCellRanges queryContentCells(short cellFlags) | ||
− | + | </syntaxhighlight> | |
which queries for cells having content as defined in the constants group <idl>com.sun.star.sheet.CellFlags</idl>. One of these cell flags is <code>FORMULA</code>. From <code>queryContentCells()</code> we receive an object with an <idl>com.sun.star.sheet.XSheetCellRanges</idl> interface, which has these methods: | which queries for cells having content as defined in the constants group <idl>com.sun.star.sheet.CellFlags</idl>. One of these cell flags is <code>FORMULA</code>. From <code>queryContentCells()</code> we receive an object with an <idl>com.sun.star.sheet.XSheetCellRanges</idl> interface, which has these methods: | ||
− | + | <syntaxhighlight lang="java"> | |
− | + | XEnumerationAccess getCells() | |
− | + | String getRangeAddressesAsString() | |
sequence< com.sun.star.table.CellRangeAddress > getRangeAddresses() | sequence< com.sun.star.table.CellRangeAddress > getRangeAddresses() | ||
− | + | </syntaxhighlight> | |
− | The method <code>getCells()</code> can be used to list all formula cells and the containing formulas in the spreadsheet document from our FirstLoadComponent example, utilizing <code>XEnumerationAccess<code>. <!--[SOURCE:FirstSteps/FirstLoadComponent.java]--> | + | The method <code>getCells()</code> can be used to list all formula cells and the containing formulas in the spreadsheet document from our FirstLoadComponent example, utilizing <code>XEnumerationAccess</code>. <!--[SOURCE:FirstSteps/FirstLoadComponent.java]--> |
− | + | <syntaxhighlight lang="java"> | |
XCellRangesQuery xCellQuery = (XCellRangesQuery)UnoRuntime.queryInterface( | XCellRangesQuery xCellQuery = (XCellRangesQuery)UnoRuntime.queryInterface( | ||
XCellRangesQuery.class, sheet); | XCellRangesQuery.class, sheet); | ||
Line 142: | Line 142: | ||
+ " contains " + xCell.getFormula()); | + " contains " + xCell.getFormula()); | ||
} | } | ||
− | + | </syntaxhighlight> | |
{{PDL1}} | {{PDL1}} | ||
− | [[Category:Documentation/ | + | [[Category:Documentation/Developer's Guide/First Steps]] |
Latest revision as of 16:05, 22 December 2020
We have already seen in the section How to get Objects in Apache OpenOffice that sets of objects can also be provided through element access methods. The three most important kinds of element access interfaces are com.sun.star.container.XNameContainer, com.sun.star.container.XIndexContainer and com.sun.star.container.XEnumeration.
The three element access interfaces are examples of how the fine-grained interfaces of the Apache OpenOffice API allow consistent object design.
All three interfaces inherit from XElementAccess
; therefore, they include the methods
type getElementType() boolean hasElements()
for finding out basic information about a set of elements. The method hasElements()
tells whether or not a set contains any elements at all; the method getElementType()
tells which type a set contains. In Java and C++, you can get information about a UNO type through com.sun.star.uno.Type
, cf, the Java UNO and the C++ UNO reference.
The com.sun.star.container.XIndexContainer and com.sun.star.container.XNameContainer interface have a parallel design. Consider both interfaces in UML notation.
The XIndexAccess/XNameAccess
interfaces are about getting an element. The XIndexReplace/XNameReplace
interfaces allow you to replace existing elements without changing the number of elements in the set, whereas the XIndexContainer/XNameContainer
interfaces allow you to increase and decrease the number of elements by inserting and removing elements.
Many sets of named or indexed objects do not support the whole inheritance hierarchy of XIndexContainer
or XNameContainer
, because the capabilities added by every subclass are not always logical for any set of elements.
The XEumerationAccess
interface works differently from named and indexed containers below the XElementAccess
interface. XEnumerationAccess
does not provide single elements like XNameAccess
and XIndexAccess
, but it creates an enumeration of objects which has methods to go to the next element as long as there are more elements.
Sets of objects sometimes support all element access methods, some also support only name, index, or enumeration access. Always look up the various types in the API reference to see which access methods are available.
For instance, the method getSheets()
at the interface com.sun.star.sheet.XSpreadsheetDocument is specified to return a com.sun.star.sheet.XSpreadsheets interface inherited from XNameContainer
. In addition, the API reference tells you that the provided object supports the com.sun.star.sheet.Spreadsheets service, which defines additional element access interfaces besides XSpreadsheets
.
Examples that show how to work with XNameAccess
, XIndexAccess
, and XEnumerationAccess
are provided below.
Name Access
The basic interface which hands out elements by name is the com.sun.star.container.XNameAccess interface. It has three methods:
any getByName( [in] string name) sequence< string > getElementNames() boolean hasByName( [in] string name)
In the FirstLoadComponent.java example above, the method getSheets()
returned a com.sun.star.sheet.XSpreadsheets interface, which inherits from XNameAccess
. Therefore, you could use getByName()
to obtain the sheet "MySheet" by name from the XSpreadsheets
container:
XSpreadsheets xSpreadsheets = xSpreadsheetDocument.getSheets(); Object sheet = xSpreadsheets.getByName("MySheet"); XSpreadsheet xSpreadsheet = (XSpreadsheet)UnoRuntime.queryInterface( XSpreadsheet.class, sheet); // use XSpreadsheet interface to get the cell A1 at position 0,0 and enter 42 as value XCell xCell = xSpreadsheet.getCellByPosition(0, 0);
Since getByName()
returns an any, you have to use AnyConverter.toObject()
and/or UnoRuntime.queryInterface()
before you can call methods at the spreadsheet object.
Index Access
The interface which hands out elements by index is the com.sun.star.container.XIndexAccess interface. It has two methods:
any getByIndex( [in] long index) long getCount()
The FirstLoadComponent example allows to demonstrate XIndexAccess
. The API reference tells us that the service returned by getSheets()
is a com.sun.star.sheet.Spreadsheet service and supports not only the interface com.sun.star.sheet.XSpreadsheets, but XIndexAccess
as well. Therefore, the sheets could have been accessed by index and not just by name by performing a query for the XIndexAccess
interface from our xSpreadsheets
variable:
XIndexAccess xSheetIndexAccess = (XIndexAccess)UnoRuntime.queryInterface( XIndexAccess.class, xSpreadsheets); Object sheet = XSheetIndexAccess.getByIndex(0);
Enumeration Access
The interface com.sun.star.container.XEnumerationAccess creates enumerations that allow traveling across a set of objects. It has one method:
com.sun.star.container.XEnumeration createEnumeration()
The enumeration object gained from createEnumeration()
supports the interface com.sun.star.container.XEnumeration. With this interface we can keep pulling elements out of the enumeration as long as it has more elements. XEnumeration
supplies the methods:
boolean hasMoreElements() any nextElement()
which are meant to build loops such as:
while (xCells.hasMoreElements()) { Object cell = xCells.nextElement(); // do something with cell }
For example, in spreadsheets you have the opportunity to find out which cells contain formulas. The resulting set of cells is provided as XEnumerationAccess
.
The interface that queries for cells with formulas is com.sun.star.sheet.XCellRangesQuery, it defines (among others) a method
XSheetCellRanges queryContentCells(short cellFlags)
which queries for cells having content as defined in the constants group com.sun.star.sheet.CellFlags. One of these cell flags is FORMULA
. From queryContentCells()
we receive an object with an com.sun.star.sheet.XSheetCellRanges interface, which has these methods:
XEnumerationAccess getCells() String getRangeAddressesAsString() sequence< com.sun.star.table.CellRangeAddress > getRangeAddresses()
The method getCells()
can be used to list all formula cells and the containing formulas in the spreadsheet document from our FirstLoadComponent example, utilizing XEnumerationAccess
.
XCellRangesQuery xCellQuery = (XCellRangesQuery)UnoRuntime.queryInterface( XCellRangesQuery.class, sheet); XSheetCellRanges xFormulaCells = xCellQuery.queryContentCells( (short)com.sun.star.sheet.CellFlags.FORMULA); XEnumerationAccess xFormulas = xFormulaCells.getCells(); XEnumeration xFormulaEnum = xFormulas.createEnumeration(); while (xFormulaEnum.hasMoreElements()) { Object formulaCell = xFormulaEnum.nextElement(); // do something with formulaCell xCell = (XCell)UnoRuntime.queryInterface(XCell.class, formulaCell); XCellAddressable xCellAddress = (XCellAddressable)UnoRuntime.queryInterface( XCellAddressable.class, xCell); System.out.print("Formula cell in column " + xCellAddress.getCellAddress().Column + ", row " + xCellAddress.getCellAddress().Row + " contains " + xCell.getFormula()); }
Content on this page is licensed under the Public Documentation License (PDL). |