offapi/com/sun/star/chart2/data/XDataProvider.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28 #ifndef com_sun_star_chart2_data_XDataProvider_idl
  29 #define com_sun_star_chart2_data_XDataProvider_idl
  30
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #include <com/sun/star/lang/IllegalArgumentException.idl>
  33 #include <com/sun/star/chart2/data/XDataSource.idl>
  34 #include <com/sun/star/beans/PropertyValue.idl>
  35 #include <com/sun/star/sheet/XRangeSelection.idl>
  36
  37 module com
  38 {
  39 module sun
  40 {
  41 module star
  42 {
  43 module chart2
  44 {
  45 module data
  46 {
  47
  48 /** An application that provides data for a chart must implement this
  49     interface.
  50  */
  51 interface XDataProvider  : ::com::sun::star::uno::XInterface
  52 {
  53     /** If <TRUE/> is returned, a call to createDataSource with the
  54         same arguments must return a valid XDataSequence object.  If
  55         <FALSE/> is returned, createDataSource throws an exception.
  56      */
  57     boolean createDataSourcePossible( [in] sequence< com::sun::star::beans::PropertyValue > aArguments );
  58
  59     /** Creates a data source object that matches the given range
  60         representation string.
  61
  62         <p>This can be used for creating the necessary data for a new
  63         chart out of a previously selected range of cells in a
  64         spreadsheet.</p>
  65
  66         @param aArguments
  67             Arguments that tell the data provider how to slice the
  68             given range.  The properties should be defined in a
  69             separate service.
  70
  71             <p>For spreadsheets and text document tables there exists a
  72             service <type>TabularDataProviderArguments</type>
  73             describing valid values for this list.</p>
  74
  75         @return
  76             a data source containing <type>DataSequence</type>s that
  77             span the entire region given in <code>aArguments</code>.
  78
  79         @throws ::com::sun::star::lang::IllegalArgumentException
  80             may be raised by the <type>XDataProvider</type> if it is
  81             unable to interpret the arguments passed in
  82              <code>aArguments</code> appropriately.
  83      */
  84     XDataSource createDataSource(
  85         [in] sequence< com::sun::star::beans::PropertyValue > aArguments )
  86         raises( com::sun::star::lang::IllegalArgumentException );
  87
  88     /** Tries to find out with what parameters the passed
  89         <type>DataSource</type> most probably was created.
  90
  91         <p>if xDataSource is a data source that was created with
  92         <member>createDataSource</member>, the arguments returned here
  93          should be the same than the ones passed to the function.
  94          Of course, this cannot be guaranteed.  However, if detection
  95          is ambiguous, the returned arguments should be empty. </p>
  96
  97         <p>This method may merge representation strings together if
  98         adjacent ranges appear successively in the range identifiers.
  99         E.g., if the first range refers to "$Sheet1.$A$1:$A$8" and the
 100         second range refers to "$Sheet1.$B$1:$B$8", those should be
 101         merged together to "$Sheet1.$A$1:$B$8".</p>
 102
 103         @param xDataSource
 104             A data source containing all data used in a chart.
 105
 106         @return
 107             Arguments that when being passed to
 108             <member>createDataSource</member> should in an ideal case
 109             return the same data source as <code>xDataSource</code>.
 110      */
 111     sequence< com::sun::star::beans::PropertyValue > detectArguments(
 112         [in] XDataSource xDataSource );
 113
 114     /** If <TRUE/> is returned, a call to
 115         createDataSequenceByRangeRepresentation with the same argument must
 116         return a valid XDataSequence object.  If <FALSE/> is returned,
 117         createDataSequenceByRangeRepresentation throws an exception.
 118      */
 119     boolean createDataSequenceByRangeRepresentationPossible( [in] string aRangeRepresentation );
 120
 121     /** creates a single data sequence for the given data range.
 122
 123         @param aRangeRepresentation
 124             is a string that can be interpreted by the component that
 125              implements this interface.  The representation string is
 126              of a form that may be used in the user interface.
 127
 128         @see createDataSource
 129
 130         @throws com::sun::star::lang::IllegalArgumentException
 131             if the given range does not contain a valid range
 132             representation for a one-dimensional range of data.
 133      */
 134     XDataSequence createDataSequenceByRangeRepresentation(
 135         [in] string aRangeRepresentation )
 136         raises( com::sun::star::lang::IllegalArgumentException );
 137
 138     /** Returns a component that is able to change a given range
 139         representation to another one.  This usually is a
 140         controller-component that uses the GUI to allow a user to
 141         select a new range.
 142
 143         <p>This method may return nothing, if it does not support
 144         range selection or if there is no current controller available
 145         that offers the functionality.</p>
 146
 147         @return
 148             The component for selecting a new range.  It must support
 149             <type>XComponent</type>, in order to inform the receiver
 150             about its lifetime.</p>
 151      */
 152     com::sun::star::sheet::XRangeSelection getRangeSelection();
 153 };
 154
 155 } ; // data
 156 } ; // chart2
 157 } ; // com
 158 } ; // sun
 159 } ; // star
 160
 161
 162 #endif
 163
 164 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */