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_chart_XChartTypeTemplate_idl
28#define com_sun_star_chart_XChartTypeTemplate_idl
29
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include <com/sun/star/uno/XInterface.idl>
32#endif
33
34#ifndef __com_sun_star_beans_PropertyValue_idl__
35#include <com/sun/star/beans/PropertyValue.idl>
36#endif
37#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
38#include <com/sun/star/lang/IllegalArgumentException.idl>
39#endif
40
41#include <com/sun/star/chart2/XDiagram.idl>
42#include <com/sun/star/chart2/data/XDataSource.idl>
43#include <com/sun/star/chart2/XChartType.idl>
44#include <com/sun/star/chart2/XDataInterpreter.idl>
45
46module com
47{
48module sun
49{
50module star
51{
52module chart2
53{
54
55interface XChartTypeTemplate : ::com::sun::star::uno::XInterface
56{
57    /** Creates a new diagram based upon the given data .
58
59        @param xDataSource
60            This data source will be interpreted in a chart-type
61            specific way and appropriate <type>DataSeries</type> will
62            be created which serve as input for the new diagram.
63
64        @param aArguments
65            Arguments that tell the template how to slice the given
66            range.  The properties should be defined in a separate
67            service.
68
69            <p>For standard parameters that may be used, see the
70            service <type>StandardDiagramCreationParameters</type>.
71            </p>
72
73        @return
74            The new diagram which represents this
75            <type>ChartTypeTemplate</type>.
76     */
77    XDiagram createDiagramByDataSource(
78        [in] data::XDataSource xDataSource,
79        [in] sequence< com::sun::star::beans::PropertyValue > aArguments );
80
81    /** @return
82            <TRUE/> if the template does support categories
83     */
84    boolean supportsCategories();
85
86    /** Analyses the given diagram and reinterprets its
87        <type>DataSeries</type> and <type>Categories</type> and
88        creates a new diagram based on these series.
89
90        <p>Note, that if <member>matchesTemplate</member> returns
91        <TRUE/> for the given <type>XDiagram</type>, the latter should
92        not be changed.</p>
93
94        @param xDiagram
95            The diagram given will be modified such that it represents
96            this <type>ChartTypeTemplate</type>.
97     */
98    void changeDiagram( [in] XDiagram xDiagram );
99
100    /** Changes the given diagram <code>xDiagram</code> by using the
101        new data given in <code>xDataSource</code>.
102
103        <p>Note that the data is interpreted in a way that fits this
104        template, but not necessarily the chart-types of the diagram.
105        This method should only be called if the data-format of the
106        diagram is compatible with the data-format of this
107        template.</p>
108
109        <p>Ideally a <member>matchesTemplate</member> call for the
110        given diagram should return <TRUE/> before this method is
111        called.</p>
112
113        @param xDataSource
114            This data source will be interpreted in a chart-type
115            specific way and the <type>DataSeries</type> found in
116            <code>xDiagram</code> will be adapted to the new data.
117            Missing data series will be created and unused ones will
118            be deleted in <code>xDiagram</code>.
119
120        @param aArguments
121            Arguments that tell the template how to slice the given
122            range.  The properties should be defined in a separate
123            service.
124
125            <p>For standard parameters that may be used, see the
126            service <type>StandardDiagramCreationParameters</type>.
127            </p>
128     */
129    void changeDiagramData(
130        [in] XDiagram xDiagram,
131        [in] data::XDataSource xDataSource,
132        [in] sequence< com::sun::star::beans::PropertyValue > aArguments );
133
134    /** States whether the given diagram could have been created by
135        the template.
136
137        <p>The template will parse the <type>DataSeriesTree</type> of
138        the diagram to determine if the structure matches the one
139        which would have been created by
140        <member>createDiagramByDataSource</member>.</p>
141
142        <p>For analysis all parts of the diagram may be used,
143        e.g. also properties set at the data series (like symbols)./p>
144
145        @param xDiagram
146            The diagram to be analyzed.
147
148        @param bAdaptProperties
149            If <TRUE/> the properties of the template are set, such
150            that the template matches more accurately.  E.g. for a
151            line-chart with symbols the property "Symbol" would be set
152            to <TRUE/>.  If this parameter is <FALSE/> the template
153            itselfs stays unmodified.
154
155        @return
156            <TRUE/> if the diagram given is structurally identical to
157            a diagram that was created using
158            <member>createDiagramByDataSource</member> or
159            <member>changeDiagram</member>.  If <FALSE/> is returned
160            the template stays unmodified even if
161            <code>bAdaptProperties</code> is <TRUE/>.
162     */
163    boolean matchesTemplate( [in] XDiagram xDiagram,
164                             [in] boolean bAdaptProperties );
165
166    /** Provides a chart type object that can be used to create new
167        series.
168
169        @param aFormerlyUsedChartTypes
170            The list can be used to copy some aspects from old charttypes during the creation of a new chart type.
171            The list might be empty.
172     */
173    XChartType getChartTypeForNewSeries( [in] sequence< XChartType > aFormerlyUsedChartTypes );
174
175    /**
176     */
177    XDataInterpreter getDataInterpreter();
178
179    /** Applies default styles to the given XDataSeries.
180
181        The default implementation assigns the system-wide chart-color defaults
182        as "Color" property to all series.
183
184        @param nIndex
185            The index of the series.  This is used to obtain a default style
186            (e.g. color) for the nth series.
187     */
188//     void applyDefaultStyle( [in] XDataSeries xSeries,
189//                             [in] long nSeriesIndex );
190
191    /** Applies a chart-type specific style (e.g. symbols) to all series in the
192        sequence aSeries.
193
194        @param xSeries
195            a single data series to which a style will be applied
196
197        @param nChartTypeGroupIndex
198            Denotes in which chart-type group the series lies, such this method
199            can apply different styles for different chart-type groups
200
201        @param nSeriesIndex
202            The index of the series inside the current chart-type group.
203            nSeriesIndex does not uniquely identify a data series alone, but
204            only together with nChartTypeGroupIndex
205
206        @param nSeriesCount
207            The number of series in the current chart-type group.
208
209        @todo In the future, this should only change the "Style" property and no
210              hard attributes.
211     */
212    void applyStyle( [in] XDataSeries xSeries,
213                     [in] long nChartTypeGroupIndex,
214                     [in] long nSeriesIndex,
215                     [in] long nSeriesCount );
216
217    /** Resets all styles that were changed from the default at any
218        object in the chart and have not been later modified.
219
220        <p>In <member>createDiagramByDataSource</member> or
221        <member>changeDiagram</member> a template might e.g. change
222        the page background color or the line style of all data
223        series.  This method should reset all objects that still have
224        the changed settings to the default.</p>
225
226        <p>If for example the template changed the
227        <type scope="com::sun::star::drawing">LineStyle</type> of all
228        series to NONE, this method should reset all series with
229        LineStyle NONE back to SOLID.  If a series has a style DASH,
230        it must not be changed.</p>
231     */
232    void resetStyles( [in] XDiagram xDiagram );
233};
234
235} ; // chart2
236} ; // com
237} ; // sun
238} ; // star
239
240#endif
241