Time measure


Measure=Time measures a date and time.

By default this is simply the current system date and time. The string representation desired for the date and / or time of the measure is then defined by using the Format option.

Options

General measure options

All general measure options are valid.

Format Default: %H:%M:%S

Display format for the string value of the measure. This can be any combination of text and Time Format codes.

An example might be:

  • Format=%A, %B %#d, %Y %#I:%M %p
    Tuesday, January 27, 2015 3:22:30 PM

If Format is not defined, the string value returned is in the default format %H:%M:%S, however the number value will be a Windows timestamp. If Format is defined, the number value will be the value defined by the format, or zero if the format does not define a numeric value.

Note: If a Format option is defined, the Windows timestamp value of the measure can still be retrieved and used with the [MeasureName:Timestamp] section variable measure modifier.

TimeStamp

The TimeStamp option is used to define an alternative to the default current system date and time used by the measure.

This option can take one of several forms:

A numeric Windows timestamp.

If TimeStamp is a numeric Windows timestamp or a formula defining a Windows timestamp, then this number, in seconds since January 1, 1601, will be used as the basis for measuring the date and time.

Daylight Saving Time codes

This can be one of several TimeStamp codes that represent various Daylight Saving Time values.

  • TimeStamp=DSTNextStart
    Returns the local date and time of the next start of Daylight Saving Time.
  • TimeStamp=DSTNextEnd
    Returns the local date and time of the next end of Daylight Saving Time.
  • TimeStamp=DSTStart
    Returns the local date and time of the start of Daylight Saving Time for the current year.
  • TimeStamp=DSTEnd
    Returns the local date and time of the end of Daylight Saving Time for the current year.
  • TimeStamp=DSTStartYYYY
    Returns the local date and time of the start of Daylight Saving Time for a defined year.
    Example: TimeStamp=DSTStart2016
  • TimeStamp=DSTEndYYYY
    Returns the local date and time of the end of Daylight Saving Time for a defined year.
    Example: TimeStamp=DSTEnd2016

Notes:These values cannot be modified with the TimeZone option to obtain valid Daylight Saving Time information for another location. These are always based on the information for the local computer.

Also see SysInfoType Time Zone values on SysInfo plugin measures.

A formatted date and time string.

TimeStamp can be any formatted date and/or time string. This might be a string the skin retrieves from a website with the WebParser plugin, or any string value that represents a date and/or time defined for the option.

Some examples might be:

  • TimeStamp=2015-01-27T15:22:30Z
  • TimeStamp=Tue, 27 Jan 2015 15:22:30
  • TimeStamp=1/27/2105 15:22:30
  • TimeStamp=Tuesday, January 27, 2015 at 15:22:30

Any date and time format can be used, as long as the constituent values can be expressed with any combination of the the Time Format codes and text. This form of the TimeStamp option MUST be used in conjunction with a matching TimeStampFormat option, which will be used to create a mask that will define the structure and values of the date and time string.

TimeStampFormat

The TimeStampFormat option creates a mask that defines the structure and values used in a matching TimeStamp formatted date and/or time string. If the TimeStamp option is not defined, or if the TimeStampFormat mask does not match the format of the TimeStamp option, an error will be produced.

The TimeStampFormat is created with any combination of the the Time Format codes and text, to create a mask of the TimeStamp option's formatted date and/or time string.

Some examples might be:

  • TimeStamp=2015-01-27T15:22:30Z
    TimeStampFormat=%Y-%m-%dT%H:%M:%SZ
  • TimeStamp=Tue, 27 Jan 2015 15:22:30
    TimeStampFormat=%a, %#d %b %Y %H:%M:%S
  • TimeStamp=1/27/2105 15:22:30
    TimeStampFormat=%#m/%#d/%Y %H:%M:%S
  • TimeStamp=Tuesday, January 27, 2015 at 15:22:30
    TimeStampFormat=%A, %B %#d, %Y at %H:%M:%S

In this usage, the TimeStamp and TimeStampFormat options are used together to turn a formatted string into a valid Windows timestamp. That timestamp value can be used for mathematical comparisons or formulas, or the Format and FormatLocale options can be used to format the timestamp any way desired for display.

Note: These values cannot evaluate any time zone information in the string and cannot be modified with the TimeZone option. What is internally arrived at by the measure is a resolution of the date and/or time string to a Windows timestamp, which is a number of seconds since January 1, 1601, and independent of any time zone.

TimeStampLocale

An optional value that defines the "language / locale" that the formatted date / time string defined in TimeStamp is in.

This will allow a TimeStamp formatted string that is in a particular language / locale to be properly resolved when TimeStampFormat is defined. The TimeStamp and TimeStampFormat options are required to use this option.

An example might be:

TimeStamp=Montag, 16. Februar 2015 13:10:45
TimeStampFormat=%A, %d. %b %Y %H:%M:%S
TimeStampLocale=de-DE

The values for this option can be found at NLS Language / Locale Identifiers. The values in the columns "Culture Name" or "Language Name Abbreviation" or "Language" can be used. Be sure to select your Windows version from the pull-down on the top left to get the most accurate information.

Hint: In addition, a combination of "Language", an "_" underscore, "Country" (from inside the parentheses in the "Locale" column) a "." dot and the value of the "ANSI Codepage" column can be used to be very specific.

Some examples might be:

  • TimeStampLocale=de-DE
    The "Culture Name" value for German - Germany
  • TimeStampLocale=FRA
    The "Language Name Abbreviation" for French
  • TimeStampLocale=Russian_Russia.1251
    The "Language"_"Country"."ANSI Codepage" for Russian - Russia using codepage 1251

Note: While the NLS Language / Locale information is included with all versions of Windows XP (Service Pack 2) or later, extraordinarily rare cases of missing or damaged information can be corrected by downloading and installing the package at Microsoft National Language Support Downlevel APIs 1.0.

FormatLocale Default: A standard English format

An optional value that defines the "language / locale" that the measure value formatted by the Format option will be displayed in.

This will allow a Time measure's value to be automatically "translated", and displayed in a particular language when used with the Format option. This will translate things like the "month name", "day of week name" and other text values to the language defined in this option.

The values for this option are the same ones defined for the TimeStampLocale option.

In addition, using the value Local, e.g. FormatLocale=Local on the measure will cause the output format to automatically use the date / time "locale" language and format set in Windows for the machine the skin is running on, rather than defaulting to a standard platform-agnostic "English" representation.

Examples might be:

TimeStamp=Wednesday, February 18, 2015 at 01:07:40
TimeStampFormat=%A, %B %#d, %Y at %H:%M:%S
TimeStampLocale=en-US
FormatLocale=de-DE
Format=%#c
Result in a String meter: Mittwoch, 18. Februar 2015 01:07:40

TimeStamp=Wednesday, February 18, 2015 at 01:07:40
TimeStampFormat=%A, %B %#d, %Y at %H:%M:%S
TimeStampLocale=en-US
FormatLocale=Local
Format=%#c
The result in a String meter will be the language and format representation appropriate for the system the skin is running on.

Note: While any Format string desired can be used, the codes like %#c that return long or short representations of the date and/or time for the system locale or the locale defined by TimeStampLocale or FormatLocal are particularly useful for easily changing between locale values from the "input" to the "output". Not only will it use the language defined by the locale, but also with the appropriate order, structure and punctuation.

TimeZone Default: local

If specified, GMT time is used, modified with the specified positive or negative offset number. E.g. TimeZone=-5 would measure the time as GMT -5.0. If not specified, or set to local, local time for the computer is used.

DaylightSavingTime Default: 1

If DaylightSavingTime is set to 0 and TimeZone is supplied, the current local offset for Daylight Saving Time is not applied to the value.

Note: All locations do not follow the same Daylight Saving Time schedule, if any. If a Time measure is intended to provide the time in a specific location, and that location follows a different schedule from the user's local system, the default value will be wrong on certain dates over the course of the year. In order to provide an accurate time, DaylightSavingTime must be set to 0, and TimeZone must be set in a way that accounts for the current Daylight Saving Time rules for that location.

Format codes

The following formatting codes are used in the Format and TimeStampFormat options.

  • %a: Abbreviated weekday name. (e.g. "Sat")
  • %A: Full weekday name. (e.g. "Saturday")
  • %b: Abbreviated month name. (e.g. "Dec")
  • %B: Full month name. (e.g. "December")
  • %c: Abbreviated date and time for system or defined locale. (e.g. "Sat Dec 26 22:55:03 2015")
  • %#c: Long date and time for system or defined locale. (e.g. "Saturday, December 26, 2015, 22:55:03")
  • %C: Century. Year divided by 100 and truncated to integer. (00 - 99)
  • %d: Day of month as number, zero padded (01 - 31).
  • %D: Short MM/DD/YY date, equivalent to %m/%d/%y (e.g. "12/26/15")
  • %e: Day of month as number, space padded. ( 1 - 31).
  • %F: Short YYYY-MM-DD date, equivalent to %Y-%m-%d (e.g. "2015-12-26")
  • %g: Week-based year, last two digits. (00 - 99)
  • %G: Week-based year. (e.g. "2015")
  • %h: Abbreviated month name, equivalent to %b. (e.g. "Dec")
  • %H: Hour in 24-hour format (00 - 23).
  • %I: Hour in 12-hour format (01 - 12).
  • %j: Day of year as number (001 - 366).
  • %m: Month as number (01 - 12).
  • %M: Minute as number (00 - 59).
  • %n: Newline character. (\n)
  • %p: AM/PM indicator for 12-hour clock.
  • %r: Full 12-hour clock time. (e.g. "10:55:03 pm")
  • %R: 24-hour HH:MM clock time. (e.g. "22:55")
  • %S: Second as number (00 - 59).
  • %t: Horizontal-tab character. (\t)
  • %T: ISO 8601 HH:MM:SS time format, equivalent to %H:%M:%S. (e.g. 22:55)
  • %u: ISO 8601 weekday as number with Monday as first day of week. (1 - 7)
  • %U: Week of year number, with the first Sunday as first day of week one. (00 - 53)
  • %V: ISO 8601 week of year number (00 - 53)
  • %w: Weekday as number with Sunday as first day of week. (0 - 6)
  • %W: Week of year as number, with first Monday as first day of week one. (00 - 53)
  • %x: Short date representation for system or defined locale. (e.g. "12/26/15")
  • %#x: Long date representation for system or defined locale. (e.g. "Saturday, December 26, 2015")
  • %X: Time representation for system or defined locale. (e.g. "22:55:03")
  • %y: Year without century (00 - 99).
  • %Y: Year with century.
  • %z: ISO 8601 offset from UTC in timezone. (e.g. "-0500")
  • %Z: Time zone name. These are for the system locale, and cannot be modified using FormatLocale. (e.g. "Eastern Standard Time")
  • %%: Percent sign.
  • locale-date: Default system date for the system locale. This code cannot be modified by using TimeStampLocale or FormatLocale.
  • locale-time: Default system time for the system locale. This code cannot be modified by using TimeStampLocale or FormatLocale.

# modifier: Removes leading zeros in the following numeric codes:
%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y

E modifier: Uses the system locale alternative representation for the following codes:
%Ec, %EC, %Ex, %EX, %Ey, %EY

O modifier: Uses the system locale alternative representation for the following codes:
%Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy

Example

[Rainmeter]
Update=1000
BackgroundMode=2
SolidColor=0,0,0,255
[MeasureDate]
Measure=Time
Format=%A, %B %#d, %Y
[Measure12HrTime]
Measure=Time
Format=%#I:%M %p
[Measure24HrTime]
Measure=Time
Format=%H:%M
[MeterText]
Meter=String
MeasureName=MeasureDate
MeasureName2=Measure12HrTime
MeasureName3=Measure24HrTime
X=5
Y=5
W=200
H=25
FontColor=255,255,255,255
Text="Date: %1, 12-hour time: %2, 24-hour time: %3"