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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef com_sun_star_chart2_data_XDataSequence_idl
  20 #define com_sun_star_chart2_data_XDataSequence_idl
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/lang/IllegalArgumentException.idl>
  24 #include <com/sun/star/chart2/data/LabelOrigin.idl>
  25 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  26
  27 module com
  28 {
  29 module sun
  30 {
  31 module star
  32 {
  33 module chart2
  34 {
  35 module data
  36 {
  37
  38 /** allows access to a one-dimensional sequence of data.
  39
  40     <p>The data that is stored in this container may contain different
  41     types.</p>
  42  */
  43 interface XDataSequence : ::com::sun::star::uno::XInterface
  44 {
  45     /** retrieves the data stored in this component.
  46
  47         @return a sequence containing the actual data.  This sequence
  48                 is a copy of the internal data.  Therefore changing
  49                 this object does not affect the content of the
  50                 XDataSequence object.
  51      */
  52     sequence< any >   getData();
  53
  54     /** returns the (UI) range representation string used by this
  55         XDataSequence.
  56      */
  57     string getSourceRangeRepresentation();
  58
  59     /** creates a label that describes the origin of this data
  60         sequence.
  61
  62         <p>This is useful, if a XLabeledDataSequence has
  63         no label sequence.  In this case you can call this method at
  64         the value sequence to obtain a fitting replacement label.</p>
  65
  66         <p>The sequence returned here may be empty if no suitable
  67         label can be generated.</p>
  68
  69         <p>The strings returned should be localized.</p>
  70
  71         @param eLabelOrigin
  72             denotes what part of the range should be used for label
  73             generation. If you have, e.g., one cell only, the
  74             parameter COLUMN enables you to get the name of the cell's
  75             column, the parameter ROW will give you its row name.
  76
  77             If you have a non quadratic range you can ask for labels for
  78             the longer side with parameter LONG_SIDE or you can obtain labels
  79             for the shorter side with parameter SHORT_SIDE.
  80
  81             If the range is not structured in a tabular way you may receive
  82             no label.
  83
  84         @return
  85             Suitable labels for the given sequence depending on the range
  86             of the sequence and the parameter <code>eLabelOrigin</code> passed.
  87             In a spreadsheet this would typically be a label like "Column x"
  88             for the short side used as DataSeries name and maybe a
  89             sequence "Row 1" "Row 2" "Row 3" for the long side to be used
  90             as categories for example.
  91
  92         Example: Assuming this sequence has a Range representation spanning
  93         row 5 and 6 in column 8. Following sequences of strings or similar strings
  94         are expected as return values:
  95
  96         generateLabel( SHORT_SIDE ) -> "Column 8"
  97         generateLabel( LONG_SIDE )  -> "Row 5" "Row 6"
  98         generateLabel( COLUMN )     -> "Column 8"
  99         generateLabel( ROW )        -> "Row 5" "Row 6"
 100
 101         Which strings exactly you return depends on the naming scheme of the application
 102         which provides its tabular data.
 103      */
 104     sequence< string > generateLabel( [in] com::sun::star::chart2::data::LabelOrigin eLabelOrigin );
 105
 106     /** returns a number format key for the value at the given index
 107         in the data sequence. If nIndex is -1, a key for the entire
 108         sequence should be returned, e.g. the most commonly used one.
 109
 110         <p>If number formats are not supported, or there is no
 111         heuristic to return a key for the entire series, return 0
 112         here.</p>
 113
 114         <p>The number format key must be valid for the
 115         com::sun::star::util::XNumberFormatsSupplier
 116         given by the XDataProvider, or 0 which is assumed
 117         to be always valid.</p>
 118      */
 119     long getNumberFormatKeyByIndex( [in] long nIndex )
 120         raises( ::com::sun::star::lang::IndexOutOfBoundsException );
 121 };
 122
 123 } ; // data
 124 } ; // chart2
 125 } ; // com
 126 } ; // sun
 127 } ; // star
 128
 129
 130 #endif
 131
 132 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */