<?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>
</conbody></concept>