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