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