/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */


module com {  module sun {  module star {  module sheet {


/** Provides methods to create new DataPilot fields where some or all items of
    this DataPilot field are grouped in some way.

    @see DataPilotField
 */
published interface XDataPilotFieldGrouping: com::sun::star::uno::XInterface
{

    /** Creates a new DataPilot field which contains a group containing the
        given DataPilot field items (members).

        <p>It is possible to create multiple groups by calling this method
        several times at the same DataPilot field. On subsequent calls, the
        DataPilot field created at the first call is used to insert the new
        groups.</p>

        <p>The collection of groups can be accessed via the
        DataPilotField::GroupInfo property. The returned
        struct contains the sequence of groups in its member
        DataPilotFieldGroupInfo::Groups.</p>

        @param aItems
            a sequence containing the names of the items (members) which will
            be part of the new group. Must be names of items contained in the
            current field.

        @returns
            the new created field if there is one created on the first call of
            this method. `NULL` is returned on subsequent calls.

        @see DataPilotField
        @see DataPilotFieldGroupInfo
     */
    XDataPilotField createNameGroup([in] sequence< string > aItems)
        raises( com::sun::star::lang::IllegalArgumentException );


    /** Groups the members of this field by dates, according to the passed
        settings.

        <p>If this field is already grouped by dates, a new DataPilot field
        will be created and returned. If this field is not grouped at all, the
        date grouping is performed inside of this field (no new field will be
        created). There must not be any other grouping (by member names or by
        numeric ranges), otherwise an exception is thrown.</p>

        @param aInfo
            contains the information how to group the items of the field. The
            members of this struct have to fulfill the following requirements:

            <ul>
            <li>If the member DataPilotFieldGroupInfo::HasAutoStart
            is set to `FALSE`, then the value of
            DataPilotFieldGroupInfo::Start must be a floating-point
            value representing a valid date/time value (if
            DataPilotFieldGroupInfo::HasAutoStart is set to `TRUE`,
            the value of DataPilotFieldGroupInfo::Start will
            be ignored).</li>

            <li>If the member DataPilotFieldGroupInfo::HasAutoEnd
            is set to `FALSE`, then the value of
            DataPilotFieldGroupInfo::End must be a floating-point
            value representing a valid date/time value( if
            DataPilotFieldGroupInfo::HasAutoEnd is set to `TRUE`,
            the value of DataPilotFieldGroupInfo::End will be
            ignored).</li>

            <li>If the members DataPilotFieldGroupInfo::HasAutoStart
            and DataPilotFieldGroupInfo::HasAutoEnd
            are set to `FALSE` both, then the value of
            DataPilotFieldGroupInfo::Start must be less than or equal
            to the value of DataPilotFieldGroupInfo::End.</li>

            <li>The member DataPilotFieldGroupInfo::HasDateValues
            must be set to `TRUE`.</li>

            <li>The member DataPilotFieldGroupInfo::Step must
            be zero, unless ranges of days have to be grouped (see the
            description of the member GroupBy below), in that case the value
            must be greater than or equal to 1 and less than or equal to 32767.
            The fractional part of the value will be ignored.</li>

            <li>The member DataPilotFieldGroupInfo::GroupBy
            must contain exactly one of the flags from DataPilotFieldGroupBy.
            A combination of several flags will not be accepted. If
            DataPilotFieldGroupBy::DAYS is specified, the
            value of the member DataPilotFieldGroupInfo::Step
            will specify the type of day grouping (see above). If that value
            is zero, grouping is performed on all days of the year (e.g. the
            members containing the 1st of January of any year are grouped
            together). If that value is greater than zero, grouping is done on
            ranges of days, and the value specifies the number of days grouped
            into one range (e.g. a value of 7 groups the members of a week
            into a range).</li>

            <li>The contents of the member
            DataPilotFieldGroupInfo::SourceField will be ignored.</li>

            <li>The contents of the member
            DataPilotFieldGroupInfo::Groups will be ignored.</li>
            </ul>

        @returns
            the new created field if there is one created. `NULL` is returned,
            if date grouping is performed inside this field (i.e. this field
            was not grouped by dates before).

        @throws com::sun::star::lang::IllegalArgumentException
            if the passed struct does not contain valid settings as described,
            or if this field is already grouped by member names or numeric
            ranges.

        @see DataPilotField
     */
    XDataPilotField createDateGroup([in] DataPilotFieldGroupInfo aInfo)
        raises( com::sun::star::lang::IllegalArgumentException );

};


}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */