]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/datetime.h
By default, always refresh editor and redraw properties when property value is changed
[wxWidgets.git] / interface / wx / datetime.h
index 70cf1c5a8998914e0223c3f85db82204b429b634..f28fd2abb349f490e34aead97d61dd25f3a76c16 100644 (file)
     used to contain the number of years, hours, minutes, seconds and
     milliseconds.
 
     used to contain the number of years, hours, minutes, seconds and
     milliseconds.
 
-
-    @section datetime_constants Constants
-
-    Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are
+    Global constant ::wxDefaultDateTime and synonym for it ::wxInvalidDateTime are
     defined. This constant will be different from any valid wxDateTime object.
 
     defined. This constant will be different from any valid wxDateTime object.
 
-    All the following constants are defined inside wxDateTime class (i.e., to
-    refer to them you should prepend their names with "wxDateTime::").
-
-    Time zone symbolic names:
-
-    @code
-    enum TZ
-    {
-        // the time in the current time zone
-        Local,
-
-        // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
-        // consequent numbers, so writing something like `GMT0 + offset' is
-        // safe if abs(offset) <= 12
-
-        // underscore stands for minus
-        GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
-        GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
-        GMT0,
-        GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
-        GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
-        // Note that GMT12 and GMT_12 are not the same: there is a difference
-        // of exactly one day between them
-
-        // some symbolic names for TZ
-
-        // Europe
-        WET = GMT0,         // Western Europe Time
-        WEST = GMT1,        // Western Europe Summer Time
-        CET = GMT1,         // Central Europe Time
-        CEST = GMT2,        // Central Europe Summer Time
-        EET = GMT2,         // Eastern Europe Time
-        EEST = GMT3,        // Eastern Europe Summer Time
-        MSK = GMT3,         // Moscow Time
-        MSD = GMT4,         // Moscow Summer Time
-
-        // US and Canada
-        AST = GMT_4,        // Atlantic Standard Time
-        ADT = GMT_3,        // Atlantic Daylight Time
-        EST = GMT_5,        // Eastern Standard Time
-        EDT = GMT_4,        // Eastern Daylight Saving Time
-        CST = GMT_6,        // Central Standard Time
-        CDT = GMT_5,        // Central Daylight Saving Time
-        MST = GMT_7,        // Mountain Standard Time
-        MDT = GMT_6,        // Mountain Daylight Saving Time
-        PST = GMT_8,        // Pacific Standard Time
-        PDT = GMT_7,        // Pacific Daylight Saving Time
-        HST = GMT_10,       // Hawaiian Standard Time
-        AKST = GMT_9,       // Alaska Standard Time
-        AKDT = GMT_8,       // Alaska Daylight Saving Time
-
-        // Australia
-
-        A_WST = GMT8,       // Western Standard Time
-        A_CST = GMT13 + 1,  // Central Standard Time (+9.5)
-        A_EST = GMT10,      // Eastern Standard Time
-        A_ESST = GMT11,     // Eastern Summer Time
-
-        // New Zealand
-        NZST = GMT12,       // Standard Time
-        NZDT = GMT13,       // Daylight Saving Time
-
-        // Universal Coordinated Time = the new and politically correct name
-        // for GMT
-        UTC = GMT0
-    };
-    @endcode
-
-    Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and
-    Inv_Month for an invalid month are the values of @c wxDateTime::Month enum.
-
-    Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values
-    in @c wxDateTime::WeekDay enum.
-
-    Finally, Inv_Year is defined to be an invalid value for year parameter.
-
-    GetMonthName() and GetWeekDayName() functions use the following flags:
-
-    @code
-    enum NameFlags
-    {
-        Name_Full = 0x01,       // return full name
-        Name_Abbr = 0x02        // return abbreviated name
-    };
-    @endcode
-
-    Several functions accept an extra parameter specifying the calendar to use
-    (although most of them only support now the Gregorian calendar). This
-    parameters is one of the following values:
-
-    @code
-    enum Calendar
-    {
-        Gregorian,  // calendar currently in use in Western countries
-        Julian      // calendar in use since -45 until the 1582 (or later)
-    };
-    @endcode
-
-    Date calculations often depend on the country and wxDateTime allows to set
-    the country whose conventions should be used using SetCountry(). It takes
-    one of the following values as parameter:
-
-    @code
-    enum Country
-    {
-        Country_Unknown, // no special information for this country
-        Country_Default, // set the default country with SetCountry() method
-                         // or use the default country with any other
-
-        Country_WesternEurope_Start,
-        Country_EEC = Country_WesternEurope_Start,
-        France,
-        Germany,
-        UK,
-        Country_WesternEurope_End = UK,
-
-        Russia,
-
-        USA
-    };
-    @endcode
-
-    Different parts of the world use different conventions for the week start.
-    In some countries, the week starts on Sunday, while in others -- on Monday.
-    The ISO standard doesn't address this issue, so we support both conventions
-    in the functions whose result depends on it (GetWeekOfYear() and
-    GetWeekOfMonth()).
-
-    The desired behvaiour may be specified by giving one of the following
-    constants as argument to these functions:
-
-    @code
-    enum WeekFlags
-    {
-        Default_First,   // Sunday_First for US, Monday_First for the rest
-        Monday_First,    // week starts with a Monday
-        Sunday_First     // week starts with a Sunday
-    };
-    @endcode
-
 
     @section datetime_static Static Functions
 
 
     @section datetime_static Static Functions
 
 class wxDateTime
 {
 public:
 class wxDateTime
 {
 public:
+    /**
+        A small unsigned integer type for storing things like minutes,
+        seconds &c. It should be at least short (i.e. not char) to contain
+        the number of milliseconds - it may also be 'int' because there is
+        no size penalty associated with it in our code, we don't store any
+        data in this format.
+    */
+    typedef unsigned short wxDateTime_t;
+
+
+    /**
+        Time zone symbolic names.
+    */
+    enum TZ
+    {
+        /// the time in the current time zone
+        Local,
+
+        //@{
+        /// zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
+        /// consequent numbers, so writing something like `GMT0 + offset' is
+        /// safe if abs(offset) <= 12
+
+        // underscore stands for minus
+        GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
+        GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
+        GMT0,
+        GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
+        GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
+        // Note that GMT12 and GMT_12 are not the same: there is a difference
+        // of exactly one day between them
+        //@}
+
+        // some symbolic names for TZ
+
+        // Europe
+        WET = GMT0,         //!< Western Europe Time
+        WEST = GMT1,        //!< Western Europe Summer Time
+        CET = GMT1,         //!< Central Europe Time
+        CEST = GMT2,        //!< Central Europe Summer Time
+        EET = GMT2,         //!< Eastern Europe Time
+        EEST = GMT3,        //!< Eastern Europe Summer Time
+        MSK = GMT3,         //!< Moscow Time
+        MSD = GMT4,         //!< Moscow Summer Time
+
+        // US and Canada
+        AST = GMT_4,        //!< Atlantic Standard Time
+        ADT = GMT_3,        //!< Atlantic Daylight Time
+        EST = GMT_5,        //!< Eastern Standard Time
+        EDT = GMT_4,        //!< Eastern Daylight Saving Time
+        CST = GMT_6,        //!< Central Standard Time
+        CDT = GMT_5,        //!< Central Daylight Saving Time
+        MST = GMT_7,        //!< Mountain Standard Time
+        MDT = GMT_6,        //!< Mountain Daylight Saving Time
+        PST = GMT_8,        //!< Pacific Standard Time
+        PDT = GMT_7,        //!< Pacific Daylight Saving Time
+        HST = GMT_10,       //!< Hawaiian Standard Time
+        AKST = GMT_9,       //!< Alaska Standard Time
+        AKDT = GMT_8,       //!< Alaska Daylight Saving Time
+
+        // Australia
+
+        A_WST = GMT8,       //!< Western Standard Time
+        A_CST = GMT13 + 1,  //!< Central Standard Time (+9.5)
+        A_EST = GMT10,      //!< Eastern Standard Time
+        A_ESST = GMT11,     //!< Eastern Summer Time
+
+        // New Zealand
+        NZST = GMT12,       //!< Standard Time
+        NZDT = GMT13,       //!< Daylight Saving Time
+
+        /// Universal Coordinated Time = the new and politically correct name
+        /// for GMT.
+        UTC = GMT0
+    };
+
+    /**
+        Several functions accept an extra parameter specifying the calendar to use
+        (although most of them only support now the Gregorian calendar). This
+        parameters is one of the following values.
+    */
+    enum Calendar
+    {
+        Gregorian,  ///< calendar currently in use in Western countries
+        Julian      ///< calendar in use since -45 until the 1582 (or later)
+    };
+
+    /**
+        Date calculations often depend on the country and wxDateTime allows to set
+        the country whose conventions should be used using SetCountry(). It takes
+        one of the following values as parameter.
+    */
+    enum Country
+    {
+        Country_Unknown, ///< no special information for this country
+        Country_Default, ///< set the default country with SetCountry() method
+                         ///< or use the default country with any other
+
+        Country_WesternEurope_Start,
+        Country_EEC = Country_WesternEurope_Start,
+        France,
+        Germany,
+        UK,
+        Country_WesternEurope_End = UK,
+
+        Russia,
+
+        USA
+    };
+
+    /// symbolic names for the months
+    enum Month
+    {
+        Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec,
+
+        /// Invalid month value.
+        Inv_Month
+    };
+
+    /// symbolic names for the weekdays
+    enum WeekDay
+    {
+        Sun, Mon, Tue, Wed, Thu, Fri, Sat,
+
+        /// Invalid week day value.
+        Inv_WeekDay
+    };
+
+    /// invalid value for the year
+    enum Year
+    {
+        Inv_Year = SHRT_MIN    // should hold in wxDateTime_t
+    };
+
+    /**
+        Flags to be used with GetMonthName() and GetWeekDayName() functions.
+    */
+    enum NameFlags
+    {
+        Name_Full = 0x01,       ///< return full name
+        Name_Abbr = 0x02        ///< return abbreviated name
+    };
+
+    /**
+        Different parts of the world use different conventions for the week start.
+        In some countries, the week starts on Sunday, while in others -- on Monday.
+        The ISO standard doesn't address this issue, so we support both conventions
+        in the functions whose result depends on it (GetWeekOfYear() and
+        GetWeekOfMonth()).
+
+        The desired behvaiour may be specified by giving one of the following
+        constants as argument to these functions.
+    */
+    enum WeekFlags
+    {
+        Default_First,   ///< Sunday_First for US, Monday_First for the rest
+        Monday_First,    ///< week starts with a Monday
+        Sunday_First     ///< week starts with a Sunday
+    };
+
+
     /**
         @name Constructors, Assignment Operators and Setters
 
     /**
         @name Constructors, Assignment Operators and Setters
 
@@ -509,8 +527,7 @@ public:
         Returns the ordinal number of the week in the month (in 1-5 range).
 
         As GetWeekOfYear(), this function supports both conventions for the
         Returns the ordinal number of the week in the month (in 1-5 range).
 
         As GetWeekOfYear(), this function supports both conventions for the
-        week start. See the description of these @c WeekFlags in the
-        @ref datetime_constants section.
+        week start.
     */
     wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
                                 const TimeZone& tz = Local) const;
     */
     wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,
                                 const TimeZone& tz = Local) const;
@@ -524,10 +541,9 @@ public:
         year. Accordingly, the week number will always be in 1-53 range (52 for
         non-leap years).
 
         year. Accordingly, the week number will always be in 1-53 range (52 for
         non-leap years).
 
-        The function depends on the @ref datetime_constants "week start"
-        convention specified by the @a flags argument but its results for
-        @c Sunday_First are not well-defined as the ISO definition quoted above
-        applies to the weeks starting on Monday only.
+        The function depends on the week start convention specified by the @a flags
+        argument but its results for @c Sunday_First are not well-defined as the
+        ISO definition quoted above applies to the weeks starting on Monday only.
     */
     wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
                                const TimeZone& tz = Local) const;
     */
     wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
                                const TimeZone& tz = Local) const;
@@ -736,8 +752,8 @@ public:
 
     /**
         This function does the same as the standard ANSI C @c strftime(3)
 
     /**
         This function does the same as the standard ANSI C @c strftime(3)
-        function. Please see its description for the meaning of @a format
-        parameter.
+        function (http://www.cplusplus.com/reference/clibrary/ctime/strftime.html).
+        Please see its description for the meaning of @a format parameter.
 
         It also accepts a few wxWidgets-specific extensions: you can optionally
         specify the width of the field to follow using @c printf(3)-like syntax
 
         It also accepts a few wxWidgets-specific extensions: you can optionally
         specify the width of the field to follow using @c printf(3)-like syntax
@@ -791,25 +807,19 @@ public:
 
         @return @NULL if the conversion failed, otherwise return the pointer
                  to the character which stopped the scan.
 
         @return @NULL if the conversion failed, otherwise return the pointer
                  to the character which stopped the scan.
+
+        @see Format()
     */
     const char* ParseDate(const wxString& date,
                            wxString::const_iterator* end = NULL);
     */
     const char* ParseDate(const wxString& date,
                            wxString::const_iterator* end = NULL);
-    /**
-        This function is like ParseDateTime(), but it only allows the date to
-        be specified. It is thus less flexible then ParseDateTime(), but also
-        has less chances to misinterpret the user input.
 
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
     const char* ParseDate(const char* date);
     */
     const char* ParseDate(const char* date);
-    /**
-        This function is like ParseDateTime(), but it only allows the date to
-        be specified. It is thus less flexible then ParseDateTime(), but also
-        has less chances to misinterpret the user input.
 
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
     const wchar_t* ParseDate(const wchar_t* date);
 
     */
     const wchar_t* ParseDate(const wchar_t* date);
 
@@ -825,26 +835,14 @@ public:
     */
     const char* ParseDateTime(const wxString& datetime,
                               wxString::const_iterator* end = NULL);
     */
     const char* ParseDateTime(const wxString& datetime,
                               wxString::const_iterator* end = NULL);
-    /**
-        Parses the string @a datetime containing the date and time in free
-        format. This function tries as hard as it can to interpret the given
-        string as date and time. Unlike ParseRfc822Date(), it will accept
-        anything that may be accepted and will only reject strings which can
-        not be parsed in any way at all.
 
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
     const char* ParseDateTime(const char* datetime);
     */
     const char* ParseDateTime(const char* datetime);
-    /**
-        Parses the string @a datetime containing the date and time in free
-        format. This function tries as hard as it can to interpret the given
-        string as date and time. Unlike ParseRfc822Date(), it will accept
-        anything that may be accepted and will only reject strings which can
-        not be parsed in any way at all.
 
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
     const wchar_t* ParseDateTime(const wchar_t* datetime);
 
     */
     const wchar_t* ParseDateTime(const wchar_t* datetime);
 
@@ -869,61 +867,27 @@ public:
 
         @return @NULL if the conversion failed, otherwise return the pointer
                  to the character which stopped the scan.
 
         @return @NULL if the conversion failed, otherwise return the pointer
                  to the character which stopped the scan.
+
+        @see Format()
     */
     const char* ParseFormat(const wxString& date,
     */
     const char* ParseFormat(const wxString& date,
-                             const wxString& format = wxDefaultDateTimeFormat,
-                             const wxDateTime& dateDef = wxDefaultDateTime,
-                             wxString::const_iterator* end = NULL);
-    /**
-        This function parses the string @a date according to the given
-        @e format. The system @c strptime(3) function is used whenever
-        available, but even if it is not, this function is still implemented,
-        although support for locale-dependent format specifiers such as
-        @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
-        as @c "%z" and @c "%Z" are not implemented. This function does handle
-        the month and weekday names in the current locale on all platforms,
-        however.
+                            const wxString& format = wxDefaultDateTimeFormat,
+                            const wxDateTime& dateDef = wxDefaultDateTime,
+                            wxString::const_iterator* end = NULL);
 
 
-        Please see the description of the ANSI C function @c strftime(3) for
-        the syntax of the format string.
-
-        The @a dateDef parameter is used to fill in the fields which could not
-        be determined from the format string. For example, if the format is
-        @c "%d" (the day of the month), the month and the year are taken from
-        @a dateDef. If it is not specified, Today() is used as the default
-        date.
-
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
     const char* ParseFormat(const char* date,
     */
     const char* ParseFormat(const char* date,
-                              const wxString& format = wxDefaultDateTimeFormat,
-                              const wxDateTime& dateDef = wxDefaultDateTime);
-    /**
-        This function parses the string @a date according to the given
-        @e format. The system @c strptime(3) function is used whenever
-        available, but even if it is not, this function is still implemented,
-        although support for locale-dependent format specifiers such as
-        @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such
-        as @c "%z" and @c "%Z" are not implemented. This function does handle
-        the month and weekday names in the current locale on all platforms,
-        however.
-
-        Please see the description of the ANSI C function @c strftime(3) for
-        the syntax of the format string.
-
-        The @a dateDef parameter is used to fill in the fields which could not
-        be determined from the format string. For example, if the format is
-        @c "%d" (the day of the month), the month and the year are taken from
-        @a dateDef. If it is not specified, Today() is used as the default
-        date.
+                            const wxString& format = wxDefaultDateTimeFormat,
+                            const wxDateTime& dateDef = wxDefaultDateTime);
 
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
     const wchar_t* ParseFormat(const wchar_t* date,
     */
     const wchar_t* ParseFormat(const wchar_t* date,
-                                 const wxString& format = wxDefaultDateTimeFormat,
-                                 const wxDateTime& dateDef = wxDefaultDateTime);
+                               const wxString& format = wxDefaultDateTimeFormat,
+                               const wxDateTime& dateDef = wxDefaultDateTime);
 
     /**
         This function parses the string containing the date and time in ISO
 
     /**
         This function parses the string containing the date and time in ISO
@@ -972,42 +936,14 @@ public:
     */
     const char* ParseRfc822Date(const wxString& date,
                                   wxString::const_iterator* end = NULL);
     */
     const char* ParseRfc822Date(const wxString& date,
                                   wxString::const_iterator* end = NULL);
-    /**
-        Parses the string @a date looking for a date formatted according to the
-        RFC 822 in it. The exact description of this format may, of course, be
-        found in the RFC (section 5), but, briefly, this is the format used in
-        the headers of Internet email messages and one of the most common
-        strings expressing date in this format may be something like
-        @c "Sat, 18 Dec 1999 00:48:30 +0100".
-
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character immediately following the part of the string which could
-        be parsed. If the entire string contains only the date in RFC 822
-        format, the returned pointer will be pointing to a @c NUL character.
 
 
-        This function is intentionally strict, it will return an error for any
-        string which is not RFC 822 compliant. If you need to parse date
-        formatted in more free ways, you should use ParseDateTime() or
-        ParseDate() instead.
+    /**
+        @overload
     */
     const char* ParseRfc822Date(const char* date);
     */
     const char* ParseRfc822Date(const char* date);
-    /**
-        Parses the string @a date looking for a date formatted according to the
-        RFC 822 in it. The exact description of this format may, of course, be
-        found in the RFC (section 5), but, briefly, this is the format used in
-        the headers of Internet email messages and one of the most common
-        strings expressing date in this format may be something like
-        @c "Sat, 18 Dec 1999 00:48:30 +0100".
-
-        Returns @NULL if the conversion failed, otherwise return the pointer to
-        the character immediately following the part of the string which could
-        be parsed. If the entire string contains only the date in RFC 822
-        format, the returned pointer will be pointing to a @c NUL character.
 
 
-        This function is intentionally strict, it will return an error for any
-        string which is not RFC 822 compliant. If you need to parse date
-        formatted in more free ways, you should use ParseDateTime() or
-        ParseDate() instead.
+    /**
+        @overload
     */
     const wchar_t* ParseRfc822Date(const wchar_t* date);
 
     */
     const wchar_t* ParseRfc822Date(const wchar_t* date);
 
@@ -1020,20 +956,14 @@ public:
     */
     const char* ParseTime(const wxString& time,
                            wxString::const_iterator* end = NULL);
     */
     const char* ParseTime(const wxString& time,
                            wxString::const_iterator* end = NULL);
-    /**
-        This functions is like ParseDateTime(), but only allows the time to be
-        specified in the input string.
 
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
     const char* ParseTime(const char* time);
     */
     const char* ParseTime(const char* time);
-    /**
-        This functions is like ParseDateTime(), but only allows the time to be
-        specified in the input string.
 
 
-        @return @NULL if the conversion failed, otherwise return the pointer
-                 to the character which stopped the scan.
+    /**
+        @overload
     */
     const wchar_t* ParseTime(const wchar_t* time);
 
     */
     const wchar_t* ParseTime(const wchar_t* time);
 
@@ -1450,9 +1380,6 @@ public:
         Sets the country to use by default. This setting influences the DST
         calculations, date formatting and other things.
 
         Sets the country to use by default. This setting influences the DST
         calculations, date formatting and other things.
 
-        The possible values for @a country parameter are enumerated in the
-        @ref datetime_constants section.
-
         @see GetCountry()
     */
     static void SetCountry(Country country);
         @see GetCountry()
     */
     static void SetCountry(Country country);