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