1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef com_sun_star_chart2_data_XDataProvider_idl
24#define com_sun_star_chart2_data_XDataProvider_idl
25
26#include <com/sun/star/uno/XInterface.idl>
27#include <com/sun/star/lang/IllegalArgumentException.idl>
28
29#include <com/sun/star/chart2/data/XDataSource.idl>
30
31#include <com/sun/star/beans/PropertyValue.idl>
32
33#include <com/sun/star/sheet/XRangeSelection.idl>
34
35module com
36{
37module sun
38{
39module star
40{
41module chart2
42{
43module data
44{
45
46/** An application that provides data for a chart must implement this
47    interface.
48 */
49interface XDataProvider  : ::com::sun::star::uno::XInterface
50{
51    /** If <TRUE/> is returned, a call to createDataSource with the
52        same arguments must return a valid XDataSequence object.  If
53        <FALSE/> is returned, createDataSource throws an exception.
54     */
55    boolean createDataSourcePossible( [in] sequence< com::sun::star::beans::PropertyValue > aArguments );
56
57    /** Creates a data source object that matches the given range
58        representation string.
59
60        <p>This can be used for creating the necessary data for a new
61        chart out of a previously selected range of cells in a
62        spreadsheet.</p>
63
64        @param aArguments
65            Arguments that tell the data provider how to slice the
66            given range.  The properties should be defined in a
67            separate service.
68
69            <p>For spreadsheets and textdocument tables there exists a
70            service <type>TabularDataProviderArguments</type>
71            describing valid values for this list.</p>
72
73        @return
74            a data source containing <type>DataSequence</type>s that
75            span the entire region given in <code>aArguments</code>.
76
77        @throws ::com::sun::star::lang::IllegalArgumentException
78            may be raised by the <type>XDataProvider</type> if it is
79            unable to interpret the arguments passed in
80	 		<code>aArguments</code> appropriately.
81     */
82    XDataSource createDataSource(
83        [in] sequence< com::sun::star::beans::PropertyValue > aArguments )
84        raises( com::sun::star::lang::IllegalArgumentException );
85
86    /** Tries to find out with what parameters the passed
87        <type>DataSource</type> most probably was created.
88
89        <p>if xDataSource is a data source that was created with
90        <member>createDataSource</member>, the arguments returned here
91	 	should be the same than the ones passed to the function.
92	 	Of course, this cannot be guaranteed.  However, if detection
93	 	is ambiguous, the returned arguments should be empty. </p>
94
95        <p>This method may merge representation strings together if
96        adjacent ranges appear successively in the range identifiers.
97        E.g., if the first range refers to "$Sheet1.$A$1:$A$8" and the
98        second range refers to "$Sheet1.$B$1:$B$8", those should be
99        merged together to "$Sheet1.$A$1:$B$8".</p>
100
101        @param xDataSource
102            A data source containing all data used in a chart.
103
104        @return
105            Arguments that when being passed to
106            <member>createDataSource</member> should in an ideal case
107            return the same data source as <code>xDataSource</code>.
108     */
109    sequence< com::sun::star::beans::PropertyValue > detectArguments(
110        [in] XDataSource xDataSource );
111
112    /** If <TRUE/> is returned, a call to
113        createDataSequenceByRangeRepresentation with the same argument must
114        return a valid XDataSequence object.  If <FALSE/> is returned,
115        createDataSequenceByRangeRepresentation throws an exception.
116     */
117    boolean createDataSequenceByRangeRepresentationPossible( [in] string aRangeRepresentation );
118
119    /** creates a single data sequence for the given data range.
120
121        @param aRangeRepresentation
122            is a string that can be interpreted by the component that
123	 		implements this interface.  The representation string is
124	 		of a form that may be used in the user interface.
125
126        @see createDataSource
127
128        @throws com::sun::star::lang::IllegalArgumentException
129            if the given range does not contain a valid range
130            representation for a one-dimensional range of data.
131     */
132    XDataSequence createDataSequenceByRangeRepresentation(
133        [in] string aRangeRepresentation )
134        raises( com::sun::star::lang::IllegalArgumentException );
135
136    /** Returns a component that is able to change a given range
137        representation to another one.  This usually is a
138        controller-component that uses the GUI to allow a user to
139        select a new range.
140
141        <p>This method may return nothing, if it does not support
142        range selection or if there is no current controller available
143        that offers the functionality.</p>
144
145        @return
146            The component for selecting a new range.  It must support
147            <type>XComponent</type>, in order to inform the receiver
148            about its lifetime.</p>
149     */
150    com::sun::star::sheet::XRangeSelection getRangeSelection();
151};
152
153} ; // data
154} ; // chart2
155} ; // com
156} ; // sun
157} ; // star
158
159
160#endif
161