/*************************************************************************
 *
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 * 
 * Copyright 2000, 2010 Oracle and/or its affiliates.
 *
 * OpenOffice.org - a multi-platform office productivity suite
 *
 * This file is part of OpenOffice.org.
 *
 * OpenOffice.org is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 3
 * only, as published by the Free Software Foundation.
 *
 * OpenOffice.org is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License version 3 for more details
 * (a copy is included in the LICENSE file that accompanied this code).
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3 along with OpenOffice.org.  If not, see
 * <http://www.openoffice.org/license.html>
 * for a copy of the LGPLv3 License.
 *
 ************************************************************************/

#ifndef __com_sun_star_i18n_XCalendar_idl__
#define __com_sun_star_i18n_XCalendar_idl__

#include <com/sun/star/lang/Locale.idl>
#include <com/sun/star/i18n/Calendar.idl>
#include <com/sun/star/i18n/CalendarItem.idl>

//============================================================================

module com { module sun { module star { module i18n {

//============================================================================

/**
    Access to locale specific calendar systems.
 */

published interface XCalendar : com::sun::star::uno::XInterface
{
    //------------------------------------------------------------------------
    /// Load the default calendar for the given locale.
    void    loadDefaultCalendar( [in] ::com::sun::star::lang::Locale rLocale );

    //------------------------------------------------------------------------
    /// Load a specific calendar for the given locale.
    void    loadCalendar( [in] string uniqueID, 
                          [in] ::com::sun::star::lang::Locale rLocale );

    //------------------------------------------------------------------------
    /// Get the currently loaded <type>Calendar</type>.
    Calendar    getLoadedCalendar();

    //------------------------------------------------------------------------
    /// Returns all available calendars for the given locale.
    sequence< string >  getAllCalendars( [in] ::com::sun::star::lang::Locale rLocale );

    //------------------------------------------------------------------------
    /** Returns the ID string of the loaded calendar, for example,
        <b>"gregorian"</b>
     */
    string  getUniqueID();

    //------------------------------------------------------------------------
    /**
        Set the date/time as an offset to the start of the calendar at
        1-Jan-1970 00:00. The integer part represents the number of days
        passed since start date. The fractional part represents
        fractions of a day, thus 0.5 means 12 hours.
     */
    void    setDateTime( [in] double nTimeInDays );

    //------------------------------------------------------------------------
    /**
        Get the date/time as an offset to the start of the calendar at
        1-Jan-1970 00:00. The integer part represents the number of days
        passed since start date. The fractional part represents
        fractions of a day, thus 0.5 means 12 hours.
     */
    double  getDateTime();

    //------------------------------------------------------------------------
    /**
        Set the value of a field.

        @param nCalendarFieldIndex
            One of <type>CalendarFieldIndex</type> values.

        @param nValue
            A value of the allowed range for the field index.
     */
    void    setValue( [in] short nCalendarFieldIndex, [in] short nValue );

    //------------------------------------------------------------------------
    /**
        Get the value of a field.

        @param nCalendarFieldIndex
            One of <type>CalendarFieldIndex</type> values.
     */
    short   getValue( [in] short nCalendarFieldIndex );

    //------------------------------------------------------------------------
    /**
        Verify if the date fields set by a combination of
        <member>XCalendar::setValue()</member> calls is valid. It has a
        side-effect because it will internally calculate the final value
        for the date fields
     */
    boolean isValid();

    //------------------------------------------------------------------------
    /**
        Add an amount to a field.

        @param nCalendarFieldIndex
            One of <type>CalendarFieldIndex</type> values.

        @param nAmount
            The amount to add.
     */
    void    addValue( [in] short nCalendarFieldIndex, [in] long nAmount );

    //------------------------------------------------------------------------
    /** returns the first day of a week, one of <type>Weekdays</type>
        values.
     */
    short   getFirstDayOfWeek();

    //------------------------------------------------------------------------
    /** Set the first day of a week, one of <type>Weekdays</type>
        values.
      */
    void    setFirstDayOfWeek( [in] short nDay );

    //------------------------------------------------------------------------
    /** Set how many days of a week must reside in the first week of a
        year.
     */
    void    setMinimumNumberOfDaysForFirstWeek( [in] short nDays );

    //------------------------------------------------------------------------
    /** returns how many days of a week must reside in the first week of
        a year.
     */
    short   getMinimumNumberOfDaysForFirstWeek();

    //------------------------------------------------------------------------
    /// returns the number of months in a year, e.g. <b>12</b>
    short   getNumberOfMonthsInYear();

    //------------------------------------------------------------------------
    /// returns the number of days in a week, e.g. <b>7</b>
    short   getNumberOfDaysInWeek();

    //------------------------------------------------------------------------
    /** returns a sequence of <type>CalendarItem</type> describing the
        month names.
     */
    sequence< CalendarItem >    getMonths();

    //------------------------------------------------------------------------
    /** returns a sequence of <type>CalendarItem</type> describing the
        day names.
     */
    sequence< CalendarItem >    getDays();

    //------------------------------------------------------------------------
    /**
        Returns a string (name to display) matching the given parameters.

        @param nCalendarDisplayIndex
            One of <type>CalendarDisplayIndex</type> values

        @param nIdx
            A value matching the <em>nCalendarDisplayIndex</em> type:
            <dl>
                <dt><const>CalendarDisplayIndex::AM_PM</const></dt>
                    <dd>one of <type>AmPmValue</type></dd>
                <dt><const>CalendarDisplayIndex::DAY</const></dt>
                    <dd>one of <type>Weekdays</type> or a number used as
                    an offset into the corresponding
                    <member>Calendar::Days</member> sequence</dd>
                <dt><const>CalendarDisplayIndex::MONTH</const></dt>
                    <dd>one of <type>Months</type> or a number used as
                    an offset into the corresponding
                    <member>Calendar::Months</member> sequence</dd>
                <dt><const>CalendarDisplayIndex::YEAR</const></dt>
                    <dd>not used, empty string returned</dd>
                <dt><const>CalendarDisplayIndex::ERA</const></dt>
                    <dd>a number used as an offset into the
                    corresponding <member>Calendar:Eras</member>
                    sequence</dd>
            </dl>

            <p> The value should be obtained by a previous call to
            <member>XCalendar::getValue()</member> with an appropriate
            <type>CalendarFieldIndex</type> argument. </p>

        @param nNameType
            A value indicating whether to return the abbreviated or the
            full name.
            <dl>
                <dt> 0 </dt>
                    <dd>abbreviated name, e.g. <b>"Jan"</b></dd>
                <dt> 1 </dt>
                    <dd>full name, e.g. <b>"January"</b></dd>

            <p> This parameter is not used if the
            <em>nCalendarDisplayIndex</em> argument equals
            <const>CalendarDisplayIndex::AM_PM</const> </p>
     */

    string  getDisplayName( [in] short nCalendarDisplayIndex, 
                            [in] short nIdx,
                            [in] short nNameType );
};

//============================================================================
}; }; }; };

#endif