xref: /aoo41x/main/offapi/com/sun/star/i18n/XCalendar.idl (revision d1766043)

/**************************************************************
 *
 * 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
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the 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