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