offapi/com/sun/star/chart2/data/XDataProvider.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_XDataProvider_idl
  20 #define com_sun_star_chart2_data_XDataProvider_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/XDataSource.idl>
  25 #include <com/sun/star/beans/PropertyValue.idl>
  26 #include <com/sun/star/sheet/XRangeSelection.idl>
  27
  28 module com
  29 {
  30 module sun
  31 {
  32 module star
  33 {
  34 module chart2
  35 {
  36 module data
  37 {
  38
  39 /** An application that provides data for a chart must implement this
  40     interface.
  41  */
  42 interface XDataProvider  : ::com::sun::star::uno::XInterface
  43 {
  44     /** If `TRUE` is returned, a call to createDataSource with the
  45         same arguments must return a valid XDataSequence object.  If
  46         `FALSE` is returned, createDataSource throws an exception.
  47      */
  48     boolean createDataSourcePossible( [in] sequence< com::sun::star::beans::PropertyValue > aArguments );
  49
  50     /** Creates a data source object that matches the given range
  51         representation string.
  52
  53         <p>This can be used for creating the necessary data for a new
  54         chart out of a previously selected range of cells in a
  55         spreadsheet.</p>
  56
  57         @param aArguments
  58             Arguments that tell the data provider how to slice the
  59             given range.  The properties should be defined in a
  60             separate service.
  61
  62             <p>For spreadsheets and text document tables there exists a
  63             service TabularDataProviderArguments
  64             describing valid values for this list.</p>
  65
  66         @return
  67             a data source containing DataSequences that
  68             span the entire region given in <code>aArguments</code>.
  69
  70         @throws ::com::sun::star::lang::IllegalArgumentException
  71             may be raised by the XDataProvider if it is
  72             unable to interpret the arguments passed in
  73              <code>aArguments</code> appropriately.
  74      */
  75     XDataSource createDataSource(
  76         [in] sequence< com::sun::star::beans::PropertyValue > aArguments )
  77         raises( com::sun::star::lang::IllegalArgumentException );
  78
  79     /** Tries to find out with what parameters the passed
  80         DataSource most probably was created.
  81
  82         <p>if xDataSource is a data source that was created with
  83         createDataSource(), the arguments returned here
  84          should be the same than the ones passed to the function.
  85          Of course, this cannot be guaranteed.  However, if detection
  86          is ambiguous, the returned arguments should be empty. </p>
  87
  88         <p>This method may merge representation strings together if
  89         adjacent ranges appear successively in the range identifiers.
  90         E.g., if the first range refers to "$Sheet1.$A$1:$A$8" and the
  91         second range refers to "$Sheet1.$B$1:$B$8", those should be
  92         merged together to "$Sheet1.$A$1:$B$8".</p>
  93
  94         @param xDataSource
  95             A data source containing all data used in a chart.
  96
  97         @return
  98             Arguments that when being passed to
  99             createDataSource() should in an ideal case
 100             return the same data source as <code>xDataSource</code>.
 101      */
 102     sequence< com::sun::star::beans::PropertyValue > detectArguments(
 103         [in] XDataSource xDataSource );
 104
 105     /** If `TRUE` is returned, a call to
 106         createDataSequenceByRangeRepresentation with the same argument must
 107         return a valid XDataSequence object.  If `FALSE` is returned,
 108         createDataSequenceByRangeRepresentation throws an exception.
 109      */
 110     boolean createDataSequenceByRangeRepresentationPossible( [in] string aRangeRepresentation );
 111
 112     /** creates a single data sequence for the given data range.
 113
 114         @param aRangeRepresentation
 115             is a string that can be interpreted by the component that
 116              implements this interface.  The representation string is
 117              of a form that may be used in the user interface.
 118
 119         @see createDataSource
 120
 121         @throws com::sun::star::lang::IllegalArgumentException
 122             if the given range does not contain a valid range
 123             representation for a one-dimensional range of data.
 124      */
 125     XDataSequence createDataSequenceByRangeRepresentation(
 126         [in] string aRangeRepresentation )
 127         raises( com::sun::star::lang::IllegalArgumentException );
 128
 129     XDataSequence createDataSequenceByValueArray( [in] string aRole, [in] string aValueArray )
 130         raises( com::sun::star::lang::IllegalArgumentException );
 131
 132     /** Returns a component that is able to change a given range
 133         representation to another one.  This usually is a
 134         controller-component that uses the GUI to allow a user to
 135         select a new range.
 136
 137         <p>This method may return nothing, if it does not support
 138         range selection or if there is no current controller available
 139         that offers the functionality.</p>
 140
 141         @return
 142             The component for selecting a new range.  It must support
 143             XComponent, in order to inform the receiver
 144             about its lifetime.</p>
 145      */
 146     com::sun::star::sheet::XRangeSelection getRangeSelection();
 147 };
 148
 149 } ; // data
 150 } ; // chart2
 151 } ; // com
 152 } ; // sun
 153 } ; // star
 154
 155
 156 #endif
 157
 158 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */