offapi/com/sun/star/chart2/data/XDataSequence.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28 #ifndef com_sun_star_chart2_data_XDataSequence_idl
  29 #define com_sun_star_chart2_data_XDataSequence_idl
  30
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #include <com/sun/star/lang/IllegalArgumentException.idl>
  33 #include <com/sun/star/chart2/data/LabelOrigin.idl>
  34 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  35
  36 module com
  37 {
  38 module sun
  39 {
  40 module star
  41 {
  42 module chart2
  43 {
  44 module data
  45 {
  46
  47 /** allows access to a one-dimensional sequence of data.
  48
  49     <p>The data that is stored in this container may contain different
  50     types.</p>
  51  */
  52 interface XDataSequence : ::com::sun::star::uno::XInterface
  53 {
  54     /** retrieves the data stored in this component.
  55
  56         @return a sequence containing the actual data.  This sequence
  57                 is a copy of the internal data.  Therefore changing
  58                 this object does not affect the content of the
  59                 XDataSequence object.
  60      */
  61     sequence< any >   getData();
  62
  63     /** returns the (UI) range representation string used by this
  64         <type>XDataSequence</type>.
  65      */
  66     string getSourceRangeRepresentation();
  67
  68     /** creates a label that describes the origin of this data
  69         sequence.
  70
  71         <p>This is useful, if a <type>XLabeledDataSequence</type> has
  72         no label sequence.  In this case you can call this method at
  73         the value sequence to obtain a fitting replacement label.</p>
  74
  75         <p>The sequence returned here may be empty if no suitable
  76         label can be generated.</p>
  77
  78         <p>The strings returned should be localized.</p>
  79
  80         @param eLabelOrigin
  81             denotes what part of the range should be used for label
  82             generation. If you have, e.g., one cell only, the
  83             parameter COLUMN enables you to get the name of the cell's
  84             column, the parameter ROW will give you its row name.
  85
  86             If you have a non quadratic range you can ask for labels for
  87             the longer side with parameter LONG_SIDE or you can obtain labels
  88             for the shorter side with parameter SHORT_SIDE.
  89
  90             If the range is not structured in a tabular way you may receive
  91             no label.
  92
  93         @return
  94             Suitable labels for the given sequence depending on the range
  95             of the sequence and the parameter <code>eLabelOrigin</code> passed.
  96             In a spreadsheet this would typically be a label like "Column x"
  97             for the short side used as DataSeries name and maybe a
  98             sequence "Row 1" "Row 2" "Row 3" for the long side to be used
  99             as categories for example.
 100
 101         Example: Assuming this sequence has a Range representation spanning
 102         row 5 and 6 in column 8. Following sequences of strings or similar strings
 103         are expected as return values:
 104
 105         generateLabel( SHORT_SIDE ) -> "Column 8"
 106         generateLabel( LONG_SIDE )  -> "Row 5" "Row 6"
 107         generateLabel( COLUMN )     -> "Column 8"
 108         generateLabel( ROW )        -> "Row 5" "Row 6"
 109
 110         Which strings exactly you return depends on the naming scheme of the application
 111         which provides its tabular data.
 112      */
 113     sequence< string > generateLabel( [in] com::sun::star::chart2::data::LabelOrigin eLabelOrigin );
 114
 115     /** returns a number format key for the value at the given index
 116         in the data sequence. If nIndex is -1, a key for the entire
 117         sequence should be returned, e.g. the most commonly used one.
 118
 119         <p>If number formats are not supported, or there is no
 120         heuristic to return a key for the entire series, return 0
 121         here.</p>
 122
 123         <p>The number format key must be valid for the
 124         <type scope="com::sun::star::util">XNumberFormatsSupplier</type>
 125         given by the <type>XDataProvider</type>, or 0 which is assumed
 126         to be always valid.</p>
 127      */
 128     long getNumberFormatKeyByIndex( [in] long nIndex )
 129         raises( ::com::sun::star::lang::IndexOutOfBoundsException );
 130 };
 131
 132 } ; // data
 133 } ; // chart2
 134 } ; // com
 135 } ; // sun
 136 } ; // star
 137
 138
 139 #endif
 140
 141 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */