Range Selection

From Apache OpenOffice Wiki
Jump to: navigation, search

The view's com.sun.star.sheet.XRangeSelection interface is used to let a user interactively select a cell range in the view, independently of the view's selection. This is used for dialogs that require a cell reference as input. While the range selection is active, a small dialog is shown, similar to the minimized state of OpenOffice.org API's own dialogs that allow cell reference input.

XRangeSelection interface

Before the range selection mode is started, a listener is registered using the addRangeSelectionListener() method. The listener implements the com.sun.star.sheet.XRangeSelectionListener interface. Its done() or aborted() method is called when the selection is finished or aborted. The com.sun.star.sheet.RangeSelectionEvent struct that is passed to the calls contains the selected range in the RangeDescriptor member. It is a string because the user can type into the minimized dialog during range selection.

In the following example, the listener implementation stores the result in a member in the done() method, and notifies the main thread about the completion of the selection in the done() and aborted() methods:

  private class ExampleRangeListener implements com.sun.star.sheet.XRangeSelectionListener {
      public String aResult;
      public void done(com.sun.star.sheet.RangeSelectionEvent aEvent) {
          aResult = aEvent.RangeDescriptor;
          synchronized (this) {
      public void aborted( com.sun.star.sheet.RangeSelectionEvent aEvent ) {
          synchronized (this) {
      public void disposing( com.sun.star.lang.EventObject aObj ) {

It is also possible to add another listener using the addRangeSelectionChangeListener() method. This listener implements the com.sun.star.sheet.XRangeSelectionChangeListener interface, and its descriptorChanged() method is called during the selection when the selection changes. Using this listener normally is not necessary.

After registering the listeners, the range selection mode is started using the startRangeSelection() method. The parameter to that method is a sequence of property values with properties from the com.sun.star.sheet.RangeSelectionArguments service:

  • InitialValue specifies an existing selection value that is shown in the dialog and highlighted in the view when the selection mode is started.
  • Title is the title for the range selection dialog.
  • CloseOnMouseRelease specifies when the selection mode is ended. If the value is true, selection is ended when the mouse button is released after selecting a cell range. If it is false or not specified, the user presses the Shrink button in the dialog to end selection mode.

The startRangeSelection() method returns immediately after starting the range selection mode. This allows it to be called from a dialog's event handler. The abortRangeSelection() method is used to cancel the range selection mode programmatically.

The following example lets the user pick a range, and then selects that range in the view. Note that the use of wait to wait for the end of the selection is not how a GUI application normally handles the events.

  // let the user select a range and use it as the view's selection
  com.sun.star.sheet.XRangeSelection xRngSel = (com.sun.star.sheet.XRangeSelection)
      UnoRuntime.queryInterface(com.sun.star.sheet.XRangeSelection.class, xController);
  ExampleRangeListener aListener = new ExampleRangeListener();
  com.sun.star.beans.PropertyValue[] aArguments = new com.sun.star.beans.PropertyValue[2];
  aArguments[0] = new com.sun.star.beans.PropertyValue();
  aArguments[0].Name = "Title";
  aArguments[0].Value = "Please select a range";
  aArguments[1] = new com.sun.star.beans.PropertyValue();
  aArguments[1].Name = "CloseOnMouseRelease";
  aArguments[1].Value = new Boolean(true);
  synchronized (aListener) {
      aListener.wait(); // wait until the selection is done
  if (aListener.aResult != null && aListener.aResult.length() != 0)
      com.sun.star.view.XSelectionSupplier xSel = (com.sun.star.view.XSelectionSupplier)
          UnoRuntime.queryInterface(com.sun.star.view.XSelectionSupplier.class, xController);
      com.sun.star.sheet.XSpreadsheetView xView = (com.sun.star.sheet.XSpreadsheetView)
          UnoRuntime.queryInterface(com.sun.star.sheet.XSpreadsheetView.class, xController);
      com.sun.star.sheet.XSpreadsheet xSheet = xView.getActiveSheet();
      com.sun.star.table.XCellRange xResultRange = xSheet.getCellRangeByName(aListener.aResult);
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages