/* -*- 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 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 Calendar.
    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 UTC 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 UTC 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 CalendarFieldIndex 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 CalendarFieldIndex values.
     */
    short   getValue( [in] short nCalendarFieldIndex );

    /**
        Verify if the date fields set by a combination of
        XCalendar::setValue() 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 CalendarFieldIndex values.

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

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

    /** Set the first day of a week, one of Weekdays
        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 CalendarItem describing the
        month names.
     */
    sequence< CalendarItem >    getMonths();

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

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

        @param nCalendarDisplayIndex
            One of CalendarDisplayIndex values

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

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

        @param nNameType
            A value indicating whether to return the abbreviated or the
            full name, or the narrow name for some 
            CalendarDisplayIndex values.
            <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>
                <dt> 2 </dt>
                    <dd>narrow name, e.g. <b>"J"</b> <br>
                    Valid only for CalendarDisplayIndex::DAY,
                    CalendarDisplayIndex::MONTH and
                    CalendarDisplayIndex::GENITIVE_MONTH <br>
                    @since LibreOffice 3.5
                    </dd>

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

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

}; }; }; };

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