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_XDataSequence_idl
24#define com_sun_star_chart2_data_XDataSequence_idl
25
26#include <com/sun/star/uno/XInterface.idl>
27#include <com/sun/star/lang/IllegalArgumentException.idl>
28#include <com/sun/star/chart2/data/LabelOrigin.idl>
29#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
30
31module com
32{
33module sun
34{
35module star
36{
37module chart2
38{
39module data
40{
41
42/** allows acces to a one-dimensional sequence of data.
43
44    <p>The data that is stored in this container may contain different
45    types.</p>
46 */
47interface XDataSequence : ::com::sun::star::uno::XInterface
48{
49    /** retrieves the data stored in this component.
50
51        @return a sequence containing the actual data.  This sequence
52                is a copy of the internal data.  Therefore changing
53                this object does not affect the content of the
54                XDataSequence object.
55     */
56    sequence< any >   getData();
57
58    /** returns the (UI) range representation string used by this
59        <type>XDataSequence</type>.
60     */
61    string getSourceRangeRepresentation();
62
63    /** creates a label that describes the origin of this data
64        sequence.
65
66        <p>This is useful, if a <type>XLabeledDataSequence</type> has
67        no label sequence.  In this case you can call this method at
68        the value sequence to obtain a fitting replacement label.</p>
69
70        <p>The sequence returned here may be empty if no suitable
71        label can be generated.</p>
72
73        <p>The strings returned should be localized.</p>
74
75        @param eLabelOrigin
76            denotes what part of the range should be used for label
77            generation. If you have, e.g., one cell only, the
78            parameter COLUMN enables you to get the name of the cell's
79            column, the parameter ROW will give you its row name.
80
81            If you have a non quadratic range you can ask for labels for
82            the longer side with parameter LONG_SIDE or you can obtain labels
83            for the shorter side with parameter SHORT_SIDE.
84
85            If the range is not structured in a tabular way you may reveive
86            no label.
87
88        @return
89            Suitable labels for the given sequence depending on the range
90            of the sequence and the parameter <code>eLabelOrigin</code> passed.
91            In a spreadsheet this would typically be a label like "Column x"
92            for the short side used as DataSeries name and maybe a
93            sequence "Row 1" "Row 2" "Row 3" for the long side to be used
94            as categories for example.
95
96        Example: Assuming this sequence has a Rangerepresentation spanning
97        row 5 and 6 in column 8. Following sequences of strings or similar strings
98        are expected as return values:
99
100        generateLabel( SHORT_SIDE ) -> "Column 8"
101        generateLabel( LONG_SIDE )  -> "Row 5" "Row 6"
102        generateLabel( COLUMN )     -> "Column 8"
103        generateLabel( ROW )        -> "Row 5" "Row 6"
104
105        Which strings exactly you return depends on the naming scheme of the application
106        which provides its tabular data.
107     */
108    sequence< string > generateLabel( [in] com::sun::star::chart2::data::LabelOrigin eLabelOrigin );
109
110    /** returns a number format key for the value at the given index
111        in the data sequence. If nIndex is -1, a key for the entire
112        sequence should be returned, e.g. the most commonly used one.
113
114        <p>If number formats are not supported, or there is no
115        heuristic to return a key for the entire series, return 0
116        here.</p>
117
118        <p>The number format key must be valid for the
119        <type scope="com::sun::star::util">XNumberFormatsSupplier</type>
120        given by the <type>XDataProvider</type>, or 0 which is assumed
121        to be always valid.</p>
122     */
123    long getNumberFormatKeyByIndex( [in] long nIndex )
124        raises( ::com::sun::star::lang::IndexOutOfBoundsException );
125};
126
127} ; // data
128} ; // chart2
129} ; // com
130} ; // sun
131} ; // star
132
133
134#endif
135