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

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