KSystemTimeZones Class Reference

from PyKDE4.kdecore import *

Inherits: QObject

Detailed Description

Abstract class:: This class can be used as a base class for new classes, but can not be instantiated directly.

The KSystemTimeZones class represents the system time zone database, consisting of a collection of individual system time zone definitions, indexed by name. Each individual time zone is defined in a KSystemTimeZone or KTzfileTimeZone instance. Additional time zones (of any class derived from KTimeZone) may be added if desired.

At initialisation, KSystemTimeZones on UNIX systems reads the zone.tab file to obtain the list of system time zones, and creates a KTzfileTimeZone instance for each one.

Note:: KSystemTimeZones gets the system's time zone configuration, including the current local system time zone and the location of zone.tab, from the KDE time zone daemon, ktimezoned. If ktimezoned cannot be started, KSystemTimeZones will only know about the UTC time zone.

Note that KSystemTimeZones is not derived from KTimeZones, but instead contains a KTimeZones instance which holds the system time zone database. Convenience static methods are defined to access its data, or alternatively you can access the KTimeZones instance directly via the timeZones() method.

As an example, find the local time in Oman corresponding to the local system time of 12:15:00 on 13th November 1999:

 QDateTime sampleTime(QDate(1999,11,13), QTime(12,15,0), Qt.LocalTime);
 KTimeZone local = KSystemTimeZones.local();
 KTimeZone oman  = KSystemTimeZones.zone("Asia/Muscat");
 QDateTime omaniTime = local.convert(oman, sampleTime);

Note:: KTzfileTimeZone is used in preference to KSystemTimeZone on UNIX systems since use of the standard system libraries by KSystemTimeZone requires the use of tzset() in several methods. That function reads and parses the local system time zone definition file every time it is called, and this has been observed to make applications hang for many seconds when a large number of KSystemTimeZone calls are made in succession.

Note:: This class provides a facility to simulate the local system time zone. This facility is provided for testing purposes only, and is only available if the library is compiled with debug enabled. In release mode, simulation is inoperative and the real local system time zone is used at all times.

System time zone access

See also:: KTimeZones, KSystemTimeZone, KSystemTimeZoneSource, KTzfileTimeZone

Author:: David Jarvie <djarvie@kde.org>.

Author:: S.R.Haque <srhaque@iee.org>.

Methods
	__init__ (self)
Static Methods
bool	isSimulated ()
bool	isTimeZoneDaemonAvailable ()
KTimeZone	local ()
KTimeZone	readZone (QString name)
KTimeZone	realLocalZone ()
	setLocalZone (KTimeZone tz)
KTimeZones	timeZones ()
KTimeZone	zone (QString name)
QString	zoneinfoDir ()
{QString:KTimeZone}	zones ()

Method Documentation

__init__ ( self )

Static Method Documentation

bool isSimulated ( )

Check whether there is a simulated local system time zone.

Warning:: This method is provided only for testing purposes, and should not be used in released code. If the library is compiled without debug enabled, isSimulated() always returns false. To avoid confusion, it is recommended that calls to it should be conditionally compiled, e.g.:

          #ifndef NDEBUG
             if (KSystemTimeZones.isSimulated())
             {
                 ...
             }
          #endif

See also:: setLocalZone()

Since:: 4.3

bool isTimeZoneDaemonAvailable ( )

Return whether the KDE time zone daemon, ktimezoned, appears to be available and working. If not, UTC will be the only recognized time zone.

Since:: 4.6

KTimeZone local ( )

Returns the current local system time zone.

The idea of this routine is to provide a robust lookup of the local time zone. On Unix systems, there are a variety of mechanisms for setting this information, and no well defined way of getting it. For example, if you set your time zone to "Europe/London", then the tzname[] maintained by tzset() typically returns { "GMT", "BST" }. The function of this routine is to actually return "Europe/London" (or rather, the corresponding KTimeZone).

Note that depending on how the system stores its current time zone, this routine may return a synonym of the expected time zone. For example, "Europe/London", "Europe/Guernsey" and some other time zones are all identical and there may be no way for the routine to distinguish which of these is the correct zone name from the user's point of view.

Warning:: For testing purposes, if the library is compiled with debug enabled, this method returns any simulated local system time zone set by setLocalZone(). If the library is compiled in release mode, it always returns the real local system time zone.

Returns:: local system time zone. If necessary, we will use a series of heuristics which end by returning UTC. We will never return NULL. Note that if UTC is returned as a default, it may not belong to the the collection returned by KSystemTimeZones.zones().

KTimeZone readZone	(	QString	name
	)

Returns the time zone with the given name, containing the full time zone definition read directly from the system time zone database. This may incur a higher overhead than zone(), but will provide whatever historical data the system holds.

Parameters:

name

name of time zone

Returns:: time zone (usually a KTzfileTimeZone instance), or invalid if not found

See also:: zone()

KTimeZone realLocalZone ( )

Return the real (not simulated) local system time zone.

Warning:: This method is provided only for testing purposes, and should not be used in released code. If the library is compiled without debug enabled, local() and realLocalZone() both return the real local system time zone. To avoid confusion, it is recommended that calls to realLocalZone() should be conditionally compiled, e.g.:

          #ifndef NDEBUG
             tz = KSystemTimeZones.realLocalZone();
          #endif

See also:: setLocalZone()

Since:: 4.3

setLocalZone	(	KTimeZone	tz
	)

Set or clear the simulated local system time zone.

Warning:: This method is provided only for testing purposes, and should not be used in released code. If the library is compiled without debug enabled, setLocalZone() has no effect. To avoid confusion, it is recommended that calls to it should be conditionally compiled, e.g.:

          #ifndef NDEBUG
             KSystemTimeZones.setLocalZone(tz);
          #endif

Parameters:

the time zone to simulate, or an invalid KTimeZone instance (i.e.

tz.isValid() == false \endcode) to cancel simulation @since 4.3

KTimeZones timeZones ( )

Returns the unique KTimeZones instance containing the system time zones collection. It is first created if it does not already exist.

Returns:: time zones.

KTimeZone zone	(	QString	name
	)

Returns the time zone with the given name.

The time zone definition is obtained using system library calls, and may not contain historical data. If you need historical time change data, use the potentially slower method readZone().

Parameters:

name

name of time zone

Returns:: time zone (usually a KSystemTimeZone instance), or invalid if not found

See also:: readZone()

QString zoneinfoDir ( )

Returns the location of the system time zone zoneinfo database.

Returns:: path of directory containing the zoneinfo database

{QString:KTimeZone} zones ( )

Returns all the time zones defined in this collection.

Returns:: time zone collection

Full Index

KSystemTimeZones Class Reference

Detailed Description

Methods

Static Methods

Method Documentation

Static Method Documentation

Modules