offapi/com/sun/star/sheet/XDataPilotFieldGrouping.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 #ifndef __com_sun_star_sheet_XDataPilotFieldGrouping_idl__
  21 #define __com_sun_star_sheet_XDataPilotFieldGrouping_idl__
  22
  23 #include <com/sun/star/uno/XInterface.idl>
  24 #include <com/sun/star/sheet/DataPilotFieldGroupInfo.idl>
  25 #include <com/sun/star/lang/IllegalArgumentException.idl>
  26
  27
  28 module com {  module sun {  module star {  module sheet {
  29
  30
  31 /** Provides methods to create new DataPilot fields where some or all items of
  32     this DataPilot field are grouped in some way.
  33
  34     @see DataPilotField
  35  */
  36 published interface XDataPilotFieldGrouping: com::sun::star::uno::XInterface
  37 {
  38
  39     /** Creates a new DataPilot field which contains a group containing the
  40         given DataPilot field items (members).
  41
  42         <p>It is possible to create multiple groups by calling this method
  43         several times at the same DataPilot field. On subsequent calls, the
  44         DataPilot field created at the first call is used to insert the new
  45         groups.</p>
  46
  47         <p>The collection of groups can be accessed via the
  48         DataPilotField::GroupInfo property. The returned
  49         struct contains the sequence of groups in its member
  50         DataPilotFieldGroupInfo::Groups.</p>
  51
  52         @param aItems
  53             a sequence containing the names of the items (members) which will
  54             be part of the new group. Must be names of items contained in the
  55             current field.
  56
  57         @returns
  58             the new created field if there is one created on the first call of
  59             this method. `NULL` is returned on subsequent calls.
  60
  61         @see DataPilotField
  62         @see DataPilotFieldGroupInfo
  63      */
  64     XDataPilotField createNameGroup([in] sequence< string > aItems)
  65         raises( com::sun::star::lang::IllegalArgumentException );
  66
  67
  68     /** Groups the members of this field by dates, according to the passed
  69         settings.
  70
  71         <p>If this field is already grouped by dates, a new DataPilot field
  72         will be created and returned. If this field is not grouped at all, the
  73         date grouping is performed inside of this field (no new field will be
  74         created). There must not be any other grouping (by member names or by
  75         numeric ranges), otherwise an exception is thrown.</p>
  76
  77         @param aInfo
  78             contains the information how to group the items of the field. The
  79             members of this struct have to fulfill the following requirements:
  80
  81             <ul>
  82             <li>If the member DataPilotFieldGroupInfo::HasAutoStart
  83             is set to `FALSE`, then the value of
  84             DataPilotFieldGroupInfo::Start must be a floating-point
  85             value representing a valid date/time value (if
  86             DataPilotFieldGroupInfo::HasAutoStart is set to `TRUE`,
  87             the value of DataPilotFieldGroupInfo::Start will
  88             be ignored).</li>
  89
  90             <li>If the member DataPilotFieldGroupInfo::HasAutoEnd
  91             is set to `FALSE`, then the value of
  92             DataPilotFieldGroupInfo::End must be a floating-point
  93             value representing a valid date/time value( if
  94             DataPilotFieldGroupInfo::HasAutoEnd is set to `TRUE`,
  95             the value of DataPilotFieldGroupInfo::End will be
  96             ignored).</li>
  97
  98             <li>If the members DataPilotFieldGroupInfo::HasAutoStart
  99             and DataPilotFieldGroupInfo::HasAutoEnd
 100             are set to `FALSE` both, then the value of
 101             DataPilotFieldGroupInfo::Start must be less than or equal
 102             to the value of DataPilotFieldGroupInfo::End.</li>
 103
 104             <li>The member DataPilotFieldGroupInfo::HasDateValues
 105             must be set to `TRUE`.</li>
 106
 107             <li>The member DataPilotFieldGroupInfo::Step must
 108             be zero, unless ranges of days have to be grouped (see the
 109             description of the member GroupBy below), in that case the value
 110             must be greater than or equal to 1 and less than or equal to 32767.
 111             The fractional part of the value will be ignored.</li>
 112
 113             <li>The member DataPilotFieldGroupInfo::GroupBy
 114             must contain exactly one of the flags from DataPilotFieldGroupBy.
 115             A combination of several flags will not be accepted. If
 116             DataPilotFieldGroupBy::DAYS is specified, the
 117             value of the member DataPilotFieldGroupInfo::Step
 118             will specify the type of day grouping (see above). If that value
 119             is zero, grouping is performed on all days of the year (e.g. the
 120             members containing the 1st of January of any year are grouped
 121             together). If that value is greater than zero, grouping is done on
 122             ranges of days, and the value specifies the number of days grouped
 123             into one range (e.g. a value of 7 groups the members of a week
 124             into a range).</li>
 125
 126             <li>The contents of the member
 127             DataPilotFieldGroupInfo::SourceField will be ignored.</li>
 128
 129             <li>The contents of the member
 130             DataPilotFieldGroupInfo::Groups will be ignored.</li>
 131             </ul>
 132
 133         @returns
 134             the new created field if there is one created. `NULL` is returned,
 135             if date grouping is performed inside this field (i.e. this field
 136             was not grouped by dates before).
 137
 138         @throws com::sun::star::lang::IllegalArgumentException
 139             if the passed struct does not contain valid settings as described,
 140             or if this field is already grouped by member names or numeric
 141             ranges.
 142
 143         @see DataPilotField
 144      */
 145     XDataPilotField createDateGroup([in] DataPilotFieldGroupInfo aInfo)
 146         raises( com::sun::star::lang::IllegalArgumentException );
 147
 148 };
 149
 150
 151 }; }; }; };
 152
 153 #endif
 154
 155 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */