docs/user/locale/TimeZone.dox

   1 /*
   2  * Copyright 2011 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Adrien Destugues, pulkomandy@pulkomandy.ath.cx
   7  *              John Scipione, jscipione@gmail.com
   8  *              Oliver Tappe, zooey@hirschkaefer.de
   9  *
  10  * Corresponds to:
  11  *              headers/os/locale/TimeZone.h     rev 42274
  12  *              src/kits/locale/TimeZone.cpp     rev 42274
  13  */
  14
  15
  16 /*!
  17         \file TimeZone.h
  18         \ingroup locale
  19         \ingroup libbe
  20         \brief Provides the BTimeZone class.
  21 */
  22
  23
  24 /*!
  25         \class BTimeZone
  26         \ingroup locale
  27         \ingroup libbe
  28         \brief Defines the time zone API which specifies a time zone, allows you to
  29                display it to the user, and converts between GMT and local time.
  30
  31         When displaying the name of a time zone to the user, use the display name,
  32         not the time zone ID. The display name can be retrieved by the
  33         BTimeZone::Name(), BTimeZone::DaylightSavingName(), BTimeZone::ShortName(),
  34         and BTimeZone::ShortDaylightSavingName() methods.
  35
  36         - The standard name looks like "Pacific Standard Time".
  37         - The daylight savings time name looks like "Pacific Daylight Time".
  38         - The short name looks like either "PST" or "PDT" depending on whether the
  39           standard or daylight savings time name is requested.
  40
  41         \sa BTimeZone::ID()
  42         \sa BTimeZone::Name()
  43         \sa BTimeZone::DaylightSavingName()
  44         \sa BTimeZone::ShortName()
  45         \sa BTimeZone::ShortDaylightSavingName()
  46
  47         \since Haiku R1
  48 */
  49
  50
  51 /*!
  52         \fn BTimeZone::BTimeZone(const char* zoneID, const BLanguage* language)
  53         \brief Construct a timezone from its \a zoneID and \a language.
  54
  55         The constructor only allows you to construct a timezone if you already
  56         know its code. If you don't know the code, you can instead go through the
  57         BCountry class which can enumerate all timezones in a country, or use the
  58         BLocaleRoster, which knows the timezone selected by the user.
  59
  60         \param zoneID A time zone ID, for example, "America/Los_Angeles".
  61                This ID is used to call up a specific real-world time zone.
  62         \param language The \a language to use when displaying the time zone.
  63
  64         \since Haiku R1
  65 */
  66
  67
  68 /*!
  69         \fn BTimeZone::BTimeZone(const BTimeZone& other)
  70         \brief Copy constructor.
  71
  72         \param other The BTimeZone object to copy from.
  73
  74         \since Haiku R1
  75 */
  76
  77
  78 /*!
  79         \fn BTimeZone& BTimeZone::operator=(const BTimeZone& source)
  80         \brief Assignment operator.
  81
  82         \param source The BTimeZone object to copy from.
  83
  84         \since Haiku R1
  85 */
  86
  87
  88 /*!
  89         \fn const BString& BTimeZone::ID() const
  90         \brief Returns the ID of the time zone as a BString, for example,
  91                "America/Los_Angeles".
  92
  93         When displaying the name of a time zone to the user, use the display name,
  94         not the time zone ID.
  95
  96         \since Haiku R1
  97 */
  98
  99
 100 /*!
 101         \fn const BString& BTimeZone::Name() const
 102         \brief Returns the localized name of the time zone, for example
 103                "Pacific Standard Time".
 104
 105         Use this method to display the time zone's name to the user.
 106
 107         \since Haiku R1
 108 */
 109
 110
 111 /*!
 112         \fn const BString& BTimeZone::DaylightSavingName() const
 113         \brief Returns the localized daylight savings name of the time zone,
 114                for example "Pacific Daylight Time".
 115
 116         \since Haiku R1
 117 */
 118
 119
 120 /*!
 121         \fn const BString& BTimeZone::ShortName() const
 122         \brief Returns the short name of the timezone, in the user's locale,
 123                for example "PST".
 124
 125         \since Haiku R1
 126 */
 127
 128
 129 /*!
 130         \fn const BString& BTimeZone::ShortDaylightSavingName() const
 131         \brief Returns the localized daylight savings name of the time zone,
 132                for example "PDT".
 133
 134         \since Haiku R1
 135 */
 136
 137
 138 /*!
 139         \fn int BTimeZone::OffsetFromGMT() const
 140         \brief Returns the offset, in milliseconds, between the standard time
 141                of a time zone and GMT.
 142
 143         Positive raw offsets are east of Greenwich, negative offsets are west of
 144         Greenwich.
 145
 146         \return The offset as a number of milliseconds from GMT, positive
 147                 or negative.
 148
 149         \since Haiku R1
 150 */
 151
 152
 153 /*!
 154         \fn bool BTimeZone::SupportsDaylightSaving() const
 155         \brief Returns whether or not if the time zone support daylight saving time.
 156
 157         \return \c true if the time zone supports daylight savings time,
 158                 \c false otherwise.
 159
 160         \since Haiku R1
 161 */
 162
 163
 164 /*!
 165         \fn status_t BTimeZone::InitCheck() const
 166         \brief Returns whether or not the constructor initialized the time zone.
 167
 168         \return \c true if BTimeZone object was initialized successfully, \c false
 169                 if there was an error initializing the BTimeZone, for instance if the
 170                 constructor or SetTo() was called with an invalid timezone ID.
 171
 172         \since Haiku R1
 173 */
 174
 175
 176 /*!
 177         \fn status_t BTimeZone::SetTo(const char* zoneCode,
 178                 const BLanguage* language)
 179         \brief Set the BTimeZone object to use a different time zone.
 180
 181         \param zoneCode The time zone ID to use, for example "America/Los_Angeles".
 182         \param language The \a language to use when displaying the time zone.
 183
 184         \return \c true if time zone was set successfully, \c false if there was an
 185                 error setting the time zone, for instance if this method was called
 186                 using an invalid \a zoneCode.
 187
 188         \since Haiku R1
 189 */