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

Revision as of 16:50, 5 October 2007

We have already seen in 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 Template:IDL, Template:IDL and Template:IDL.

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, i.e., they include the methods:

  type getElementType()
  boolean hasElements()

to find out basic information about the set of elements. The method hasElements() 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 com.sun.star.uno.Type, cf, the Java UNO and the C++ UNO reference.

The Template:IDL and Template:IDL 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 Template:IDL is specified to return a Template:IDL interface inherited from XNameContainer. In addition, the API reference tells you that the provided object supports the Template:IDL 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 Template:IDL interface. It has three methods:

  any getByName( [in] string name)
  sequence< string > getElementNames()
  boolean hasByName( [in] string name)

In the FirstLoadComponent example above, the method getSheets() returned a Template:IDL 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()<(code> before you can call methods at the spreadsheet object.

  any getByIndex( [in] long index)
  long getCount()

The FirstLoadComponent example allows to demonstrate <code>XIndexAccess. The API reference tells us that the service returned by getSheets() is a Template:IDL service and supports not only the interface Template:IDL, 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 Template:IDL 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 Template:IDL. With this interface we can keep pulling elements out of the enumeration as long as it has more elements. XEnumeration supplies the methods:

  booleanhasMoreElements()
  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 Template:IDL, it defines (among others) a method

  XSheetCellRanges queryContentCells(short cellFlags)

which queries for cells having content as defined in the constants group Template:IDL. One of these cell flags is FORMULA. From queryContentCells() we receive an object with an Template:IDL interface, which has these methods:

  XEnumerationAccessgetCells()
  StringgetRangeAddressesAsString()
  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<code>.

  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());
  }