Difference between revisions of "Documentation/DevGuide/FirstSteps/Element Access"

From Apache OpenOffice Wiki
Jump to: navigation, search
(FINAL VERSION FOR L10N)
 
(18 intermediate revisions by 8 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 OpenOffice.org]] that sets of objects can also be provided through element access methods. The three most important kinds of element access interfaces are [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XNameContainer.html com.sun.star.container.XNameContainer], [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XIndexContainer.html com.sun.star.container.XIndexContainer] and [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XEnumeration.html com.sun.star.container.XEnumeration].
+
We have already seen in the section [[Documentation/DevGuide/FirstSteps/How to get Objects in OpenOffice.org|How to get Objects in OpenOffice.org]] 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 {{PRODUCTNAME}} API allow consistent object design.
 
The three element access interfaces are examples of how the fine-grained interfaces of the {{PRODUCTNAME}} API allow consistent object design.
  
All three interfaces inherit from <code>XElementAccess</code>, i.e., they include the methods:
+
All three interfaces inherit from <code>XElementAccess</code>; therefore, they include the methods
  
 +
  <source lang="java">
 
   type getElementType()
 
   type getElementType()
 
   boolean hasElements()
 
   boolean hasElements()
 +
  </source>
  
to find out basic information about the set of elements. The method <code>hasElements()</code> answers the question if a set contains elements at all, and 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.
+
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 [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XIndexContainer.html com.sun.star.container.XIndexContainer] and [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XNameContainer.html com.sun.star.container.XNameContainer] 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.
  
 
[[Image:XNameIndexContainer.png|none|thumb|400px|Indexed and Named Container]]
 
[[Image:XNameIndexContainer.png|none|thumb|400px|Indexed and Named Container]]
Line 31: Line 34:
 
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.
 
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 <code>getSheets()</code> at the interface [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/XSpreadsheetDocument.html com.sun.star.sheet.XSpreadsheetDocument] is specified to return a [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/XSpreadsheets.html com.sun.star.sheet.XSpreadsheets] interface inherited from <code>XNameContainer</code>. In addition, the API reference tells you that the provided object supports the [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/Spreadsheets.html com.sun.star.sheet.Spreadsheets] service, which defines additional element access interfaces besides <code>XSpreadsheets</code>.
+
For instance, the method <code>getSheets()</code> at the interface <idl>com.sun.star.sheet.XSpreadsheetDocument</idl> is specified to return a <idl>com.sun.star.sheet.XSpreadsheets</idl> interface inherited from <code>XNameContainer</code>. In addition, the API reference tells you that the provided object supports the <idl>com.sun.star.sheet.Spreadsheets</idl> service, which defines additional element access interfaces besides <code>XSpreadsheets</code>.
  
 
Examples that show how to work with <code>XNameAccess</code>, <code>XIndexAccess</code>, and <code>XEnumerationAccess</code> are provided below.
 
Examples that show how to work with <code>XNameAccess</code>, <code>XIndexAccess</code>, and <code>XEnumerationAccess</code> are provided below.
  
 
===Name Access===
 
===Name Access===
The basic interface which hands out elements by name is the [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XNameAccess.html com.sun.star.container.XNameAccess] 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:
  
 +
  <source 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)
 +
  </source>
  
In the FirstLoadComponent example above, the method <code>getSheets()</code> returned a [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/XSpreadsheets.html com.sun.star.sheet.XSpreadsheets] 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:
  
 +
  <source lang="java">
 
   XSpreadsheets xSpreadsheets = xSpreadsheetDocument.getSheets();
 
   XSpreadsheets xSpreadsheets = xSpreadsheetDocument.getSheets();
 
    
 
    
Line 52: 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);
 +
  </source>
  
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.
+
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 [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XIndexAccess.html com.sun.star.container.XIndexAccess] 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:
  
 +
  <source lang="java">
 
   any getByIndex( [in] long index)
 
   any getByIndex( [in] long index)
 
   long getCount()
 
   long getCount()
 +
  </source>
  
The FirstLoadComponent example allows to demonstrate <code>XIndexAccess</code>. The API reference tells us that the service returned by <code>getSheets()</code> is a [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/Spreadsheet.html com.sun.star.sheet.Spreadsheet] service and supports not only the interface [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/XSpreadsheets.html com.sun.star.sheet.XSpreadsheets], 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:
  
 +
  <source 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);
 +
  </source>
  
 
===Enumeration Access===
 
===Enumeration Access===
The interface [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XEnumerationAccess.html com.sun.star.container.XEnumerationAccess] 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:
  
 +
  <source lang="java">
 
   com.sun.star.container.XEnumeration createEnumeration()
 
   com.sun.star.container.XEnumeration createEnumeration()
 +
  </source>
  
The enumeration object gained from <code>createEnumeration()</code> supports the interface [http://api.openoffice.org/docs/common/ref/com/sun/star/container/XEnumeration.html com.sun.star.container.XEnumeration]. 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:
  
   booleanhasMoreElements()
+
   <source lang="java">
 +
  boolean hasMoreElements()
 
   any nextElement()
 
   any nextElement()
 +
  </source>
  
 
which are meant to build loops such as:
 
which are meant to build loops such as:
  
 +
  <source lang="java">
 
   while (xCells.hasMoreElements()) {
 
   while (xCells.hasMoreElements()) {
 
    
 
    
Line 85: Line 101:
 
       // do something with cell  
 
       // do something with cell  
 
   }
 
   }
 +
  </source>
  
 
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>.
 
   
 
   
The interface that queries for cells with formulas is [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/XCellRangesQuery.html com.sun.star.sheet.XCellRangesQuery], 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
  
 +
  <source lang="java">
 
   XSheetCellRanges queryContentCells(short cellFlags)
 
   XSheetCellRanges queryContentCells(short cellFlags)
 +
  </source>
  
which queries for cells having content as defined in the constants group [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/CellFlags.html com.sun.star.sheet.CellFlags]. One of these cell flags is <code>FORMULA</code>. From <code>queryContentCells()</code> we receive an object with an [http://api.openoffice.org/docs/common/ref/com/sun/star/sheet/XSheetCellRanges.html com.sun.star.sheet.XSheetCellRanges] 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:
  
   XEnumerationAccessgetCells()
+
   <source lang="java">
   StringgetRangeAddressesAsString()
+
  XEnumerationAccess getCells()
 +
   String getRangeAddressesAsString()
 
   sequence< com.sun.star.table.CellRangeAddress > getRangeAddresses()
 
   sequence< com.sun.star.table.CellRangeAddress > getRangeAddresses()
 +
  </source>
  
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]-->
  
 +
  <source lang="java">
 
   XCellRangesQuery xCellQuery = (XCellRangesQuery)UnoRuntime.queryInterface(
 
   XCellRangesQuery xCellQuery = (XCellRangesQuery)UnoRuntime.queryInterface(
 
       XCellRangesQuery.class, sheet);
 
       XCellRangesQuery.class, sheet);
Line 120: Line 142:
 
           + " contains " + xCell.getFormula());
 
           + " contains " + xCell.getFormula());
 
   }
 
   }
 +
  </source>
  
 
{{PDL1}}
 
{{PDL1}}
[[Category: First Steps]]
+
 
 +
[[Category:Documentation/Developer's Guide/First Steps]]

Latest revision as of 09:18, 18 May 2009



We have already seen in the section How to get Objects in OpenOffice.org 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 OpenOffice.org 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.

Indexed and Named Container

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.

Enumerated Container

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).
Personal tools
In other languages