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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef __com_sun_star_i18n_XCalendar_idl__
  21 #define __com_sun_star_i18n_XCalendar_idl__
  22
  23 #include <com/sun/star/lang/Locale.idl>
  24 #include <com/sun/star/i18n/Calendar.idl>
  25 #include <com/sun/star/i18n/CalendarItem.idl>
  26
  27
  28 module com { module sun { module star { module i18n {
  29
  30
  31 /**
  32     Access to locale specific calendar systems.
  33  */
  34
  35 published interface XCalendar : com::sun::star::uno::XInterface
  36 {
  37     /// Load the default calendar for the given locale.
  38     void    loadDefaultCalendar( [in] ::com::sun::star::lang::Locale rLocale );
  39
  40     /// Load a specific calendar for the given locale.
  41     void    loadCalendar( [in] string uniqueID,
  42                           [in] ::com::sun::star::lang::Locale rLocale );
  43
  44     /// Get the currently loaded Calendar.
  45     Calendar    getLoadedCalendar();
  46
  47     /// Returns all available calendars for the given locale.
  48     sequence< string >  getAllCalendars( [in] ::com::sun::star::lang::Locale rLocale );
  49
  50     /** Returns the ID string of the loaded calendar, for example,
  51         <b>"Gregorian"</b>
  52      */
  53     string  getUniqueID();
  54
  55     /**
  56         Set the UTC date/time as an offset to the start of the calendar
  57         at 1-Jan-1970 00:00. The integer part represents the number of
  58         days passed since start date. The fractional part represents
  59         fractions of a day, thus 0.5 means 12 hours.
  60      */
  61     void    setDateTime( [in] double nTimeInDays );
  62
  63     /**
  64         Get the UTC date/time as an offset to the start of the calendar
  65         at 1-Jan-1970 00:00. The integer part represents the number of
  66         days passed since start date. The fractional part represents
  67         fractions of a day, thus 0.5 means 12 hours.
  68      */
  69     double  getDateTime();
  70
  71     /**
  72         Set the value of a field.
  73
  74         @param nCalendarFieldIndex
  75             One of CalendarFieldIndex values.
  76
  77         @param nValue
  78             A value of the allowed range for the field index.
  79      */
  80     void    setValue( [in] short nCalendarFieldIndex, [in] short nValue );
  81
  82     /**
  83         Get the value of a field.
  84
  85         @param nCalendarFieldIndex
  86             One of CalendarFieldIndex values.
  87      */
  88     short   getValue( [in] short nCalendarFieldIndex );
  89
  90     /**
  91         Verify if the date fields set by a combination of
  92         XCalendar::setValue() calls is valid. It has a
  93         side-effect because it will internally calculate the final value
  94         for the date fields
  95      */
  96     boolean isValid();
  97
  98     /**
  99         Add an amount to a field.
 100
 101         @param nCalendarFieldIndex
 102             One of CalendarFieldIndex values.
 103
 104         @param nAmount
 105             The amount to add.
 106      */
 107     void    addValue( [in] short nCalendarFieldIndex, [in] long nAmount );
 108
 109     /** returns the first day of a week, one of Weekdays
 110         values.
 111      */
 112     short   getFirstDayOfWeek();
 113
 114     /** Set the first day of a week, one of Weekdays
 115         values.
 116       */
 117     void    setFirstDayOfWeek( [in] short nDay );
 118
 119     /** Set how many days of a week must reside in the first week of a
 120         year.
 121      */
 122     void    setMinimumNumberOfDaysForFirstWeek( [in] short nDays );
 123
 124     /** returns how many days of a week must reside in the first week of
 125         a year.
 126      */
 127     short   getMinimumNumberOfDaysForFirstWeek();
 128
 129     /// returns the number of months in a year, e.g. <b>12</b>
 130     short   getNumberOfMonthsInYear();
 131
 132     /// returns the number of days in a week, e.g. <b>7</b>
 133     short   getNumberOfDaysInWeek();
 134
 135     /** returns a sequence of CalendarItem describing the
 136         month names.
 137      */
 138     sequence< CalendarItem >    getMonths();
 139
 140     /** returns a sequence of CalendarItem describing the
 141         day names.
 142      */
 143     sequence< CalendarItem >    getDays();
 144
 145     /**
 146         Returns a string (name to display) matching the given parameters.
 147
 148         @param nCalendarDisplayIndex
 149             One of CalendarDisplayIndex values
 150
 151         @param nIdx
 152             A value matching the <em>nCalendarDisplayIndex</em> type:
 153             <dl>
 154                 <dt>CalendarDisplayIndex::AM_PM</dt>
 155                     <dd>one of AmPmValue</dd>
 156                 <dt>CalendarDisplayIndex::DAY</dt>
 157                     <dd>one of Weekdays or a number used as
 158                     an offset into the corresponding
 159                     Calendar::Days sequence</dd>
 160                 <dt>CalendarDisplayIndex::MONTH</dt>
 161                     <dd>one of Months or a number used as
 162                     an offset into the corresponding
 163                     Calendar::Months sequence</dd>
 164                 <dt>CalendarDisplayIndex::YEAR</dt>
 165                     <dd>not used, empty string returned</dd>
 166                 <dt>CalendarDisplayIndex::ERA</dt>
 167                     <dd>a number used as an offset into the
 168                     corresponding Calendar:Eras
 169                     sequence</dd>
 170                 <dt>CalendarDisplayIndex::GENITIVE_MONTH</dt>
 171                     <dd>a number used as an offset into the
 172                     corresponding Calendar2:GenitiveMonth
 173                     sequence</dd>
 174             </dl>
 175
 176             <p> The value should be obtained by a previous call to
 177             XCalendar::getValue() with an appropriate
 178             CalendarFieldIndex argument. </p>
 179
 180         @param nNameType
 181             A value indicating whether to return the abbreviated or the
 182             full name, or the narrow name for some
 183             CalendarDisplayIndex values.
 184             <dl>
 185                 <dt> 0 </dt>
 186                     <dd>abbreviated name, e.g. <b>"Jan"</b></dd>
 187                 <dt> 1 </dt>
 188                     <dd>full name, e.g. <b>"January"</b></dd>
 189                 <dt> 2 </dt>
 190                     <dd>narrow name, e.g. <b>"J"</b> <br>
 191                     Valid only for CalendarDisplayIndex::DAY,
 192                     CalendarDisplayIndex::MONTH and
 193                     CalendarDisplayIndex::GENITIVE_MONTH <br>
 194                     @since LibreOffice 3.5
 195                     </dd>
 196
 197             <p> This parameter is not used if the
 198             <em>nCalendarDisplayIndex</em> argument equals
 199             CalendarDisplayIndex::AM_PM </p>
 200      */
 201
 202     string  getDisplayName( [in] short nCalendarDisplayIndex,
 203                             [in] short nIdx,
 204                             [in] short nNameType );
 205 };
 206
 207 }; }; }; };
 208
 209 #endif
 210
 211 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */