/*************************************************************************
 *
 *  $RCSfile: XCalendar.idl,v $
 *
 *  $Revision: 1.8.4.2 $
 *
 *  last change: $Author: mi $ $Date: 2003/01/21 17:44:41 $
 *
 *  The Contents of this file are made available subject to the terms of
 *  either of the following licenses
 *
 *         - GNU Lesser General Public License Version 2.1
 *         - Sun Industry Standards Source License Version 1.1
 *
 *  Sun Microsystems Inc., October, 2000
 *
 *  GNU Lesser General Public License Version 2.1
 *  =============================================
 *  Copyright 2000 by Sun Microsystems, Inc.
 *  901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License version 2.1, as published by the Free Software Foundation.
 *
 *  This library 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 for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *  MA  02111-1307  USA
 *
 *
 *  Sun Industry Standards Source License Version 1.1
 *  =================================================
 *  The contents of this file are subject to the Sun Industry Standards
 *  Source License Version 1.1 (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.openoffice.org/license.html.
 *
 *  Software provided under this License is provided on an "AS IS" basis,
 *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
 *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
 *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
 *  See the License for the specific provisions governing your rights and
 *  obligations concerning the Software.
 *
 *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
 *
 *  Copyright: 2000 by Sun Microsystems, Inc.
 *
 *  All Rights Reserved.
 *
 *  Contributor(s): _______________________________________
 *
 *
 ************************************************************************/

#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.
 */

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
