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