offapi/com/sun/star/sheet/XDataPilotFieldGrouping.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XDataPilotFieldGrouping.idl,v $
  10  * $Revision: 1.4 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_sheet_XDataPilotFieldGrouping_idl__
  32 #define __com_sun_star_sheet_XDataPilotFieldGrouping_idl__
  33
  34 #ifndef __com_sun_star_uno_XInterface_idl__
  35 #include <com/sun/star/uno/XInterface.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_sheet_DataPilotFieldGroupInfo_idl__
  39 #include <com/sun/star/sheet/DataPilotFieldGroupInfo.idl>
  40 #endif
  41 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  42 #include <com/sun/star/lang/IllegalArgumentException.idl>
  43 #endif
  44
  45 //=============================================================================
  46
  47 module com {  module sun {  module star {  module sheet {
  48
  49 //=============================================================================
  50
  51 /** Provides methods to create new DataPilot fields where some or all items of
  52     this DataPilot field are grouped in some way.
  53
  54     @see DataPilotField
  55  */
  56 published interface XDataPilotFieldGrouping: com::sun::star::uno::XInterface
  57 {
  58     //-------------------------------------------------------------------------
  59
  60     /** Creates a new DataPilot field which contains a group containing the
  61         given DataPilot field items (members).
  62
  63         <p>It is possible to create multiple groups by calling this method
  64         several times at the same DataPilot field. On subsequent calls, the
  65         DataPilot field created at the first call is used to insert the new
  66         groups.</p>
  67
  68         <p>The collection of groups can be accessed via the
  69         <member>DataPilotField::GroupInfo</member> property. The returned
  70         struct contains the sequence of groups in its member
  71         <member>DataPilotFieldGroupInfo::Groups</member>.</p>
  72
  73         @param aItems
  74             a sequence containing the names of the items (members) which will
  75             be part of the new group. Must be names of items contained in the
  76             current field.
  77
  78         @returns
  79             the new created field if there is one created on the first call of
  80             this method. <NULL/> is returned on subsequent calls.
  81
  82         @see DataPilotField
  83         @see DataPilotFieldGroupInfo
  84      */
  85     XDataPilotField createNameGroup([in] sequence< string > aItems)
  86         raises( com::sun::star::lang::IllegalArgumentException );
  87
  88     //-------------------------------------------------------------------------
  89
  90     /** Groups the members of this field by dates, according to the passed
  91         settings.
  92
  93         <p>If this field is already grouped by dates, a new DataPilot field
  94         will be created and returned. If this field is not grouped at all, the
  95         date grouping is perfomed inside of this field (no new field will be
  96         created). There must not be any other grouping (by member names or by
  97         numeric ranges), otherwise an exception is thrown.</p>
  98
  99         @param aInfo
 100             contains the information how to group the items of the field. The
 101             members of this struct have to fulfill the following requirements:
 102
 103             <ul>
 104             <li>If the member <member>DataPilotFieldGroupInfo::HasAutoStart
 105             </member> is set to <FALSE/>, then the value of <member>
 106             DataPilotFieldGroupInfo::Start</member> must be a floating-point
 107             value representing a valid date/time value (if <member>
 108             DataPilotFieldGroupInfo::HasAutoStart</member> is set to <TRUE/>,
 109             the value of <member>DataPilotFieldGroupInfo::Start</member> will
 110             be ignored).</li>
 111
 112             <li>If the member <member>DataPilotFieldGroupInfo::HasAutoEnd
 113             </member> is set to <FALSE/>, then the value of <member>
 114             DataPilotFieldGroupInfo::End</member> must be a floating-point
 115             value representing a valid date/time value( if <member>
 116             DataPilotFieldGroupInfo::HasAutoEnd</member> is set to <TRUE/>,
 117             the value of <member>DataPilotFieldGroupInfo::End</member> will be
 118             ignored).</li>
 119
 120             <li>If the members <member>DataPilotFieldGroupInfo::HasAutoStart
 121             </member> and <member>DataPilotFieldGroupInfo::HasAutoEnd</member>
 122             are set to <FALSE/> both, then the value of <member>
 123             DataPilotFieldGroupInfo::Start</member> must be less than or equal
 124             to the value of <member>DataPilotFieldGroupInfo::End</member>.</li>
 125
 126             <li>The member <member>DataPilotFieldGroupInfo::HasDateValues</member>
 127             must be set to <TRUE/>.</li>
 128
 129             <li>The member <member>DataPilotFieldGroupInfo::Step</member> must
 130             be zero, unless ranges of days have to be grouped (see the
 131             description of the member GroupBy below), in that case the value
 132             must be greater than or equal to 1 and less than or equal to 32767.
 133             The fractional part of the value will be ignored.</li>
 134
 135             <li>The member <member>DataPilotFieldGroupInfo::GroupBy</member>
 136             must contain exactly one of the flags from <type>DataPilotFieldGroupBy</type>.
 137             A combination of several flags will not be accepted. If
 138             <const>DataPilotFieldGroupBy::DAYS</const> is specified, the
 139             value of the member <member>DataPilotFieldGroupInfo::Step</member>
 140             will specify the type of day grouping (see above). If that value
 141             is zero, grouping is performed on all days of the year (e.g. the
 142             members containing the 1st of January of any year are grouped
 143             together). If that value is greater than zero, grouping is done on
 144             ranges of days, and the value specifies the number of days grouped
 145             into one range (e.g. a value of 7 groups the members of a week
 146             into a range).</li>
 147
 148             <li>The contents of the member <member>
 149             DataPilotFieldGroupInfo::SourceField</member> will be ignored.</li>
 150
 151             <li>The contents of the member <member>
 152             DataPilotFieldGroupInfo::Groups</member> will be ignored.</li>
 153             </ul>
 154
 155         @returns
 156             the new created field if there is one created. <NULL/> is returned,
 157             if date grouping is performed inside this field (i.e. this field
 158             was not grouped by dates before).
 159
 160         @throws com::sun::star::lang::IllegalArgumentException
 161             if the passed struct does not contain valid settings as described,
 162             or if this field is already grouped by member names or numeric
 163             ranges.
 164
 165         @see DataPilotField
 166      */
 167     XDataPilotField createDateGroup([in] DataPilotFieldGroupInfo aInfo)
 168         raises( com::sun::star::lang::IllegalArgumentException );
 169
 170 };
 171
 172 //=============================================================================
 173
 174 }; }; }; };
 175
 176 #endif
 177