<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-B002BA13-38FA-590C-A1A9-336867BBFDBE" xml:lang="en"><title>timezonelocalization:

Time Zone Localization example</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Download</title> <p>Click on the following link

to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-f9f2a7c6-8e13-4308-851d-64fbec0736e4.zip" scope="external"> TZLocExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-f9f2a7c6-8e13-4308-851d-64fbec0736e4.html" scope="peer">browse</xref> to view the example code. </p> </section>

<section><title> Description</title> <p>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. </p> <p>It first

creates an instance of <xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita"><apiname>CTzLocalizer</apiname></xref>, which is the interface

to the localized time zone and city name information. Note that <codeph>ReadUserData</codeph> and <codeph>WriteUserData</codeph> capabilities

are needed to instantiate class <xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita"><apiname>CTzLocalizer</apiname></xref>. <xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita"><apiname>CTzLocalizer</apiname></xref> is

used to retrieve and display a list of all available localized time zone names

(contained in a <xref href="GUID-77031C53-5BB3-3022-B03C-8D3EAFFCFB78.dita"><apiname>CTzLocalizedTimeZoneArray</apiname></xref>). The array is

sorted by standard name (<xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita#GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950/GUID-C89F7E6F-4470-342A-962A-D8ABF24B6F6F"><apiname>CTzLocalizer::ETzAlphaStandardNameAscending</apiname></xref>)

but could be sorted in various other ways, for instance by UTC offset. </p> <p>Each

localized time zone (<xref href="GUID-35BC25A8-ED6D-36A1-8D28-3BA278AD84FE.dita"><apiname>CTzLocalizedTimeZone</apiname></xref>) 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. <xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita"><apiname>CTzLocalizer</apiname></xref> reads the resources

from the appropriate resource file for the system's current language setting. </p> <p>The

example then adds a new city to a time zone and city group using <xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita#GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950/GUID-FB27B31A-DCA9-31CB-A051-F6135B91F353"><apiname>CTzLocalizer::AddCityL()</apiname></xref>.

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. </p> <p>City groups (<xref href="GUID-8BA1973D-91DF-382B-BB73-07AE2FEFA0B7.dita"><apiname>CTzLocalizedCityGroup</apiname></xref>)

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. </p> <p>The example

displays all cities in the chosen time zone (using <xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita#GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950/GUID-710B9CB0-894E-3862-ADA9-E533621E676E"><apiname>CTzLocalizer::GetCitiesL()</apiname></xref>)

and all cities in the chosen city group (using <xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita#GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950/GUID-D289CB62-683F-3E52-94A5-ACCF58D4D2CA"><apiname>CTzLocalizer::GetCitiesInGroupL()</apiname></xref>). </p> </section>

<section><title>Usage</title><p> This is a console application, so does not

have a GUI. It builds an executable called <filepath>TzLocExample.exe</filepath> in

the standard location (<filepath>\epoc32\release\winscw</filepath>\&lt;build_variant&gt;

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.</p> </section>

<section><title>Class Summary</title><p> <xref href="GUID-18853D2C-A730-38CD-AA3D-3B1F4E891950.dita"><apiname>CTzLocalizer</apiname></xref> </p><p> <xref href="GUID-EA9E57AA-D0B8-377E-B52D-A4AE645B8A12.dita"><apiname>CTzLocalizedCity</apiname></xref>  </p><p><xref href="GUID-52662291-BC7B-385D-A338-9AA97FD7E242.dita"><apiname>CTzLocalizedCityArray</apiname></xref>  </p><p><xref href="GUID-8BA1973D-91DF-382B-BB73-07AE2FEFA0B7.dita"><apiname>CTzLocalizedCityGroup</apiname></xref> </p><p> <xref href="GUID-ECFB8BAC-05EB-300F-A178-43CB5DF3A388.dita"><apiname>CTzLocalizedCityGroupArray</apiname></xref> </p><p> <xref href="GUID-35BC25A8-ED6D-36A1-8D28-3BA278AD84FE.dita"><apiname>CTzLocalizedTimeZone</apiname></xref></p><p>  <xref href="GUID-77031C53-5BB3-3022-B03C-8D3EAFFCFB78.dita"><apiname>CTzLocalizedTimeZoneArray</apiname></xref>  </p></section>