timezonelocalization: Using Time Zone Localization

Found in examples\AppServices\timezonelocalization\.

This example demonstrates the Time Zone Localization API. The purpose of the API is to provide access to the localizable names of time zones, cities and city groups.

It first creates an instance of CTzLocalizer, which is the interface to the localized time zone and city name information. Note that ReadUserData and WriteUserData capabilities are needed to instantiate class CTzLocalizer. CTzLocalizer is used to retrieve and display a list of all available localized time zone names (contained in a CTzLocalizedTimeZoneArray). The array is sorted by standard name (CTzLocalizer::ETzAlphaStandardNameAscending) but could be sorted in various other ways, for instance by UTC offset.

Each localized time zone (CTzLocalizedTimeZone) is identified by a numeric ID, and has up to four names: a standard name, a short standard name, a daylight savings (DST) name and short DST name. Localized time zone information is defined in language-specific resource files installed in the ROM, each of which contains the time zone names and city names translated into the appropriate language. CTzLocalizer reads the resources from the appropriate resource file for the system's current language setting.

The example then adds a new city to a time zone and city group using CTzLocalizer::AddCityL(). It first checks that the city has not already been added, (no two cities with the same name can be in the same time zone). The cities in a time zone are a combination of static data, stored in the time zone resource files in ROM, and user defined data, stored separately, in a database. However, the location of the data is hidden from users of the API.

City groups (CTzLocalizedCityGroup) are an optional way of grouping cities other than by time zone. Each city group has an ID and a name. As city group names are localizable, they are also defined in language-specific resource files in the ROM.

The example displays all cities in the chosen time zone (using CTzLocalizer::GetCitiesL()) and all cities in the chosen city group (using CTzLocalizer::GetCitiesInGroupL()).

This is a console application, so does not have a GUI. It builds an executable called TzLocExample.exe in the standard location (\epoc32\release\winscw\<build_variant> for CodeWarrior). The Symbian OS build process describes how to build this application. After launching the executable, depending on the emulator you are using, you may need to task away from the app launcher/shell screen to view the console.

Alternatively, adding the string textshell to the emulator configuration file epoc.ini causes the emulator to start in text mode. You may need to copy the executable into the emulator's file system, then it can be launched from the text shell.