offapi/com/sun/star/i18n/XCalendar.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28
  29 #ifndef __com_sun_star_i18n_XCalendar_idl__
  30 #define __com_sun_star_i18n_XCalendar_idl__
  31
  32 #include <com/sun/star/lang/Locale.idl>
  33 #include <com/sun/star/i18n/Calendar.idl>
  34 #include <com/sun/star/i18n/CalendarItem.idl>
  35
  36 //============================================================================
  37
  38 module com { module sun { module star { module i18n {
  39
  40 //============================================================================
  41
  42 /**
  43     Access to locale specific calendar systems.
  44  */
  45
  46 published interface XCalendar : com::sun::star::uno::XInterface
  47 {
  48     //------------------------------------------------------------------------
  49     /// Load the default calendar for the given locale.
  50     void    loadDefaultCalendar( [in] ::com::sun::star::lang::Locale rLocale );
  51
  52     //------------------------------------------------------------------------
  53     /// Load a specific calendar for the given locale.
  54     void    loadCalendar( [in] string uniqueID,
  55                           [in] ::com::sun::star::lang::Locale rLocale );
  56
  57     //------------------------------------------------------------------------
  58     /// Get the currently loaded <type>Calendar</type>.
  59     Calendar    getLoadedCalendar();
  60
  61     //------------------------------------------------------------------------
  62     /// Returns all available calendars for the given locale.
  63     sequence< string >  getAllCalendars( [in] ::com::sun::star::lang::Locale rLocale );
  64
  65     //------------------------------------------------------------------------
  66     /** Returns the ID string of the loaded calendar, for example,
  67         <b>"Gregorian"</b>
  68      */
  69     string  getUniqueID();
  70
  71     //------------------------------------------------------------------------
  72     /**
  73         Set the date/time as an offset to the start of the calendar at
  74         1-Jan-1970 00:00. The integer part represents the number of days
  75         passed since start date. The fractional part represents
  76         fractions of a day, thus 0.5 means 12 hours.
  77      */
  78     void    setDateTime( [in] double nTimeInDays );
  79
  80     //------------------------------------------------------------------------
  81     /**
  82         Get the date/time as an offset to the start of the calendar at
  83         1-Jan-1970 00:00. The integer part represents the number of days
  84         passed since start date. The fractional part represents
  85         fractions of a day, thus 0.5 means 12 hours.
  86      */
  87     double  getDateTime();
  88
  89     //------------------------------------------------------------------------
  90     /**
  91         Set the value of a field.
  92
  93         @param nCalendarFieldIndex
  94             One of <type>CalendarFieldIndex</type> values.
  95
  96         @param nValue
  97             A value of the allowed range for the field index.
  98      */
  99     void    setValue( [in] short nCalendarFieldIndex, [in] short nValue );
 100
 101     //------------------------------------------------------------------------
 102     /**
 103         Get the value of a field.
 104
 105         @param nCalendarFieldIndex
 106             One of <type>CalendarFieldIndex</type> values.
 107      */
 108     short   getValue( [in] short nCalendarFieldIndex );
 109
 110     //------------------------------------------------------------------------
 111     /**
 112         Verify if the date fields set by a combination of
 113         <member>XCalendar::setValue()</member> calls is valid. It has a
 114         side-effect because it will internally calculate the final value
 115         for the date fields
 116      */
 117     boolean isValid();
 118
 119     //------------------------------------------------------------------------
 120     /**
 121         Add an amount to a field.
 122
 123         @param nCalendarFieldIndex
 124             One of <type>CalendarFieldIndex</type> values.
 125
 126         @param nAmount
 127             The amount to add.
 128      */
 129     void    addValue( [in] short nCalendarFieldIndex, [in] long nAmount );
 130
 131     //------------------------------------------------------------------------
 132     /** returns the first day of a week, one of <type>Weekdays</type>
 133         values.
 134      */
 135     short   getFirstDayOfWeek();
 136
 137     //------------------------------------------------------------------------
 138     /** Set the first day of a week, one of <type>Weekdays</type>
 139         values.
 140       */
 141     void    setFirstDayOfWeek( [in] short nDay );
 142
 143     //------------------------------------------------------------------------
 144     /** Set how many days of a week must reside in the first week of a
 145         year.
 146      */
 147     void    setMinimumNumberOfDaysForFirstWeek( [in] short nDays );
 148
 149     //------------------------------------------------------------------------
 150     /** returns how many days of a week must reside in the first week of
 151         a year.
 152      */
 153     short   getMinimumNumberOfDaysForFirstWeek();
 154
 155     //------------------------------------------------------------------------
 156     /// returns the number of months in a year, e.g. <b>12</b>
 157     short   getNumberOfMonthsInYear();
 158
 159     //------------------------------------------------------------------------
 160     /// returns the number of days in a week, e.g. <b>7</b>
 161     short   getNumberOfDaysInWeek();
 162
 163     //------------------------------------------------------------------------
 164     /** returns a sequence of <type>CalendarItem</type> describing the
 165         month names.
 166      */
 167     sequence< CalendarItem >    getMonths();
 168
 169     //------------------------------------------------------------------------
 170     /** returns a sequence of <type>CalendarItem</type> describing the
 171         day names.
 172      */
 173     sequence< CalendarItem >    getDays();
 174
 175     //------------------------------------------------------------------------
 176     /**
 177         Returns a string (name to display) matching the given parameters.
 178
 179         @param nCalendarDisplayIndex
 180             One of <type>CalendarDisplayIndex</type> values
 181
 182         @param nIdx
 183             A value matching the <em>nCalendarDisplayIndex</em> type:
 184             <dl>
 185                 <dt><const>CalendarDisplayIndex::AM_PM</const></dt>
 186                     <dd>one of <type>AmPmValue</type></dd>
 187                 <dt><const>CalendarDisplayIndex::DAY</const></dt>
 188                     <dd>one of <type>Weekdays</type> or a number used as
 189                     an offset into the corresponding
 190                     <member>Calendar::Days</member> sequence</dd>
 191                 <dt><const>CalendarDisplayIndex::MONTH</const></dt>
 192                     <dd>one of <type>Months</type> or a number used as
 193                     an offset into the corresponding
 194                     <member>Calendar::Months</member> sequence</dd>
 195                 <dt><const>CalendarDisplayIndex::YEAR</const></dt>
 196                     <dd>not used, empty string returned</dd>
 197                 <dt><const>CalendarDisplayIndex::ERA</const></dt>
 198                     <dd>a number used as an offset into the
 199                     corresponding <member>Calendar:Eras</member>
 200                     sequence</dd>
 201                 <dt><const>CalendarDisplayIndex::GENITIVE_MONTH</const></dt>
 202                     <dd>a number used as an offset into the
 203                     corresponding <member>Calendar2:GenitiveMonth</member>
 204                     sequence</dd>
 205             </dl>
 206
 207             <p> The value should be obtained by a previous call to
 208             <member>XCalendar::getValue()</member> with an appropriate
 209             <type>CalendarFieldIndex</type> argument. </p>
 210
 211         @param nNameType
 212             A value indicating whether to return the abbreviated or the
 213             full name, or the narrow name for some
 214             <type>CalendarDisplayIndex</type> values.
 215             <dl>
 216                 <dt> 0 </dt>
 217                     <dd>abbreviated name, e.g. <b>"Jan"</b></dd>
 218                 <dt> 1 </dt>
 219                     <dd>full name, e.g. <b>"January"</b></dd>
 220                 <dt> 2 </dt>
 221                     <dd>narrow name, e.g. <b>"J"</b> <br>
 222                     Valid only for <const>CalendarDisplayIndex::DAY</const>,
 223                     <const>CalendarDisplayIndex::MONTH</const> and
 224                     <const>CalendarDisplayIndex::GENITIVE_MONTH</const> <br>
 225                     @since LibreOffice 3.5
 226                     </dd>
 227
 228             <p> This parameter is not used if the
 229             <em>nCalendarDisplayIndex</em> argument equals
 230             <const>CalendarDisplayIndex::AM_PM</const> </p>
 231      */
 232
 233     string  getDisplayName( [in] short nCalendarDisplayIndex,
 234                             [in] short nIdx,
 235                             [in] short nNameType );
 236 };
 237
 238 //============================================================================
 239 }; }; }; };
 240
 241 #endif
 242
 243 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */