org.symbian.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_planning_the_widget-GUID-891068c7-c802-4da7-8674-8e8292aef7eb.html
author tasneems@symbian.org
Thu, 04 Mar 2010 15:42:37 -0800
changeset 220 41890dfa56f5
permissions -rw-r--r--
Fixed 2046 - added support for WRTKit help
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
220
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     1
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     2
<html lang="en" xml:lang="en">
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     3
<head>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     4
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     5
<meta name="copyright" content="(C) Copyright 2005" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     6
<meta name="DC.rights.owner" content="(C) Copyright 2005" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     7
<meta content="concept" name="DC.Type" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     8
<meta name="DC.Title" content="Planning the widget" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
     9
<meta scheme="URI" name="DC.Relation" content="WRTKit_Travel_Companion_Tutorial-GUID-be79ba64-fa03-4968-964e-d7dcc42d7053.html" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    10
<meta content="XHTML" name="DC.Format" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    11
<meta content="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB" name="DC.Identifier" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    12
<meta content="en" name="DC.Language" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    13
<link href="commonltr.css" type="text/css" rel="stylesheet" />
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    14
<title>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    15
Planning the widget</title>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    16
</head>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    17
<body id="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB"><a name="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB"><!-- --></a>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    18
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    19
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    20
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    21
    <h1 class="topictitle1">
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    22
Planning the widget</h1>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    23
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    24
    <div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    25
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    26
        <div class="section"><h2 class="sectiontitle">
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    27
Designing the user interface</h2>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    28
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    29
            
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    30
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    31
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    32
                Because the Travel Companion is such a complex widget it is important to plan
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    33
                both the user interface and implementation carefully before starting to write
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    34
                any code. What are the most common use cases that we want to address with this
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    35
                widget? How will typical users be using the widget? What kind of future features
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    36
                might there be and can we plan for those already?
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    37
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    38
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    39
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    40
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    41
                Because the Travel Companion widget offers so much functionality and information
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    42
                it is important to present it in such a way that it doesn't overwhelm the user.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    43
                To give the user a better idea of what is available and how to get to everything,
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    44
                we'll have a main view with nothing but navigation buttons to the other views in
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    45
                the widget. We'll implement this view using WRTKit NavigationButton controls and
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    46
                we will give each button its own icon so that the user can quickly see what the
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    47
                view is about.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    48
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    49
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    50
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    51
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    52
                After some planning and talking to potential users we have decided to create
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    53
                a summary view that we will call "information view". This view will include the
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    54
                most important information in a single place so that the user can view it quickly
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    55
                without having to press any buttons to navigate around the widget. We'll put a
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    56
                world clock here, the current weather at home and at the local destination, and
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    57
                the latest news headlines. The information view will be entirely composed from
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    58
                WRTKit ContentPanel controls.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    59
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    60
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    61
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    62
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    63
                In addition to the information view we'll have two more specialized views. We'll
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    64
                have a currency converter with two TextField controls (one for the home currency
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    65
                and one for the local) and two FormButton controls. One button will convert
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    66
                from the home currency to local currency and the other button will convert in the
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    67
                other direction. The second specialized view is a five day weather forecast. Like
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    68
                the information view this will be using ContentPanel controls and we will share
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    69
                the weather content used for the information view for this view.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    70
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    71
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    72
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    73
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    74
                Finally we'll have a settings view that is accessible from the main view just like
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    75
                the other views in the widget. In many other widgets we might want to hide access
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    76
                to the settings view to the Options menu but in this case one of the common use
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    77
                cases is to configure where in the world you are so rather than hiding access to
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    78
                the view we want to present it clearly in the main view. The settings view will
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    79
                use SelectionMenu controls to allow users to select their home and local cities,
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    80
                SelectionList controls with a single option that will be presented as a checkbox
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    81
                to configure whether the cities are in daylight saving time or not, and a
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    82
                SelectionList control that lets the user select the temperature unit to use in
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    83
                the weather forecasts. Finally there will be two FormButton controls to let the
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    84
                user save or cancel any settings changes.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    85
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    86
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    87
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    88
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    89
                When the widget starts will setup a timer that will call a timer callback function
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    90
                once every second. In the callback function we will check what view is currently
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    91
                active and we'll update the views (e.g. clock) so that the views stays up to date
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    92
                even if the user doesn't do anything. After all, the most common use case is to
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    93
                just have the information view open and not do anything other than glance at the
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    94
                information that is displayed.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    95
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    96
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    97
        </div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    98
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
    99
        <div class="section"><h2 class="sectiontitle">
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   100
Travel Companion widget files</h2>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   101
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   102
            
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   103
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   104
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   105
                All the files - HTML, CSS, JavaScript and images - have been created for you.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   106
                You can find the completed widget with all its files in the Examples/TravelCompanion
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   107
                directory in the WRTKit SDK. The tutorial will assume that you will create your
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   108
                own Travel Companion widget by following the instructions but if you prefer you can
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   109
                just open up the ready made files and examine them as you read the tutorial. If you
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   110
                are creating the widget from scratch by following the tutorial's instructions then
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   111
                we suggest that you create a working directory for the new widget and copy over all
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   112
                other ready made files except TravelCompanion.js. All of our work will be on this
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   113
                file, but before we move on to that file we'll take a look at what other files the
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   114
                widget is using.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   115
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   116
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   117
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   118
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   119
                Since we're using the WRTKit to implement our user interface we have the WRTKit
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   120
                library with all its files in a directory called "WRTKit".
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   121
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   122
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   123
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   124
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   125
                Like all widgets the Travel Companion has an Info.plist widget metadata file and an
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   126
                icon in a file called Icon.png. You'll also notice that there's a bunch of png
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   127
                image files in the widget directory. There's a file called ListViewCaptionLogo.png
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   128
                that we will use as a custom graphical element in the view caption in all of our
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   129
                views. Four png files have names starting with "Nav" and the rest start with
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   130
                "Weather". The image files that have names starting with "Nav" are icons for the
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   131
                NavigationButton controls for the main view. They are simply images that are
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   132
                30 by 30 pixels in size and have some graphical motif that captures what the button
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   133
                does. Note that the size of images used for navigation buttons doesn't have to be
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   134
                exactly 30 by 30 pixels - you can use any size you like. The images with names
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   135
                starting with "Weather" are images used in the weather forecasts. There is one image
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   136
                for each kind of weather that can be forecasted: rain, snow, sunshine, clouds, etc.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   137
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   138
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   139
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   140
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   141
                You'll find two JavaScript files: Engine.js and TravelCompanion.js. The Engine.js
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   142
                file has the implementation of the business logic and the TravelCompanion.js file
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   143
                implements the widget and its user interface. Finally there is the main widget HTML
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   144
                file called TravelCompanion.html and a CSS file called TravelCompanion.css that
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   145
                contains all the style rules used in the widget - above that what the WRTKit defines
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   146
                by default, which is actually nearly everything!
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   147
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   148
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   149
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   150
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   151
                Let's take a quick peek at TravelCompanion.html:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   152
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   153
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   154
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   155
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   156
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   157
&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   158
&lt;html xmlns="http://www.w3.org/1999/xhtml"&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   159
    &lt;head&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   160
        &lt;title&gt;&lt;/title&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   161
        &lt;script type="text/javascript" src="WRTKit/WRTKit.js"&gt;&lt;/script&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   162
        &lt;script type="text/javascript" src="Engine.js"&gt;&lt;/script&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   163
        &lt;script type="text/javascript" src="TravelCompanion.js"&gt;&lt;/script&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   164
        &lt;style type="text/css"&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   165
            @import url("TravelCompanion.css");
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   166
        &lt;/style&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   167
    &lt;/head&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   168
    &lt;body onload="init()"&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   169
    &lt;/body&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   170
&lt;/html&gt;
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   171
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   172
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   173
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   174
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   175
                If you've gone through the Hello World and/or RSS Reader tutorials then this should
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   176
                look very familiar. The file has no content, includes the WRTKit.js file from the
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   177
                WRTKit library directory, includes the JavaScript files that we are using to implement
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   178
                the Travel Companion widget, includes the TravelCompanion.css stylesheet file, and
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   179
                finally calls a function called init() when the widget has loaded everything.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   180
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   181
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   182
        </div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   183
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   184
        <div class="section"><h2 class="sectiontitle">
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   185
The Travel Companion Engine</h2>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   186
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   187
            
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   188
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   189
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   190
                Following good software engineering principles, we are implementing the Travel Companion
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   191
                widget so that the user interface is decoupled from the implementation of the actual
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   192
                business logic that knows weather forecasts, calculates currency conversions, etc. The
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   193
                logic is outside of the scope for this tutorial since we're interested in learning about
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   194
                how to use the WRTKit - not how to convert euros to dollars. Because of this we will not
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   195
                look at all at how the business logic is implemented but we will take a close look at
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   196
                the interface between the user interface and the business logic engine. In fact, the 
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   197
                implementation of the engine for this example is a mock implementation and only mimics
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   198
                what a real engine would do. But since this is only an example that's quite alright.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   199
                The engine interface, however, is identical to what it would be even if the engine would
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   200
                have a real implementation.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   201
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   202
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   203
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   204
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   205
                The engine is implemented as a JavaScript class that you instantiate before using.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   206
                The reason for being implemented as a class is simply so that the engine can better
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   207
                encapsulate its internal data and provide a kind of name space for its methods.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   208
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   209
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   210
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   211
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   212
                The core concept in the Travel Companion engine is that of cities. The engine supports
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   213
                a list of cities and one will always be a "home city" and one a "local city". The
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   214
                same city can be both home and local. Home refers to the city where the user lives
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   215
                and local refers to the city where the user is currently located. The engine doesn't
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   216
                know the daylight saving time schedules for cities so this is configured manually by
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   217
                the user: one setting for the home city and one for the local city. The engine handles
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   218
                all preferences but the user interface must tell it to save preferences if some
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   219
                preference is modified. Preferences are automatically loaded when the engine is
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   220
                created, which should happen when the widget starts so that all the settings are
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   221
                available immediately.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   222
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   223
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   224
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   225
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   226
                A city in the engine is a JavaScript object. A city object has the following public
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   227
                properties: name for the city name, currency for the three-letter currency abbreviation, 
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   228
                and timezone for the timezone code (e.g. GMT). Cities are created and managed entirely
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   229
                by the engine.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   230
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   231
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   232
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   233
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   234
                Below is a complete list of the public engine APIs that are related to preferences and
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   235
                cities:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   236
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   237
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   238
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   239
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   240
                Loading and saving preferences:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   241
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   242
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   243
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   244
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   245
[void] Engine.loadPreferences(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   246
[void] Engine.savePreferences(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   247
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   248
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   249
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   250
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   251
                Retrieving all cities supported by the engine:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   252
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   253
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   254
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   255
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   256
[Array] Engine.getCities(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   257
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   258
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   259
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   260
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   261
                Retrieving a city based on its name:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   262
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   263
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   264
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   265
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   266
[City] Engine.getCityByName(String name)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   267
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   268
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   269
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   270
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   271
                Retrieving and settting the home city:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   272
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   273
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   274
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   275
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   276
[City] Engine.getHomeCity(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   277
[void] Engine.setHomeCity(City city)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   278
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   279
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   280
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   281
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   282
                Retrieving and settting the home city daylight saving time setting:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   283
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   284
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   285
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   286
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   287
[Boolean] Engine.getHomeCityDST(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   288
[void] Engine.setHomeCityDST(Boolean dst)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   289
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   290
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   291
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   292
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   293
                Retrieving and settting the local city:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   294
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   295
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   296
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   297
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   298
[City] Engine.getLocalCity(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   299
[void] Engine.setLocalCity(City city)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   300
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   301
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   302
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   303
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   304
                Retrieving and settting the local city daylight saving time setting:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   305
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   306
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   307
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   308
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   309
[Boolean] Engine.getLocalCityDST(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   310
[void] Engine.setLocalCityDST(Boolean dst)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   311
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   312
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   313
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   314
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   315
                Retrieving and setting the preferred temperature unit:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   316
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   317
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   318
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   319
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   320
[String] Engine.getTemperatureUnit(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   321
[void] Engine.setTemperatureUnit(String unit)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   322
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   323
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   324
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   325
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   326
                Of course the engine isn't just about preferences. Its actual purpose is to perform
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   327
                various operations related to these cities, such as converting currencies, figuring
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   328
                out what the time is in a foreign city, etc. To simplify the usage of the engine,
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   329
                the public methods related to these operations are defined in terms of the home and
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   330
                local city as it is configured at the time when the method is called.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   331
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   332
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   333
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   334
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   335
                Here's the full list of the actual operation methods that the engine supports:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   336
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   337
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   338
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   339
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   340
                Currency conversions between home and local:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   341
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   342
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   343
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   344
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   345
[Float] Engine.convertHomeToLocalMoney(Float amount)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   346
[Float] Engine.convertLocalToHomeMoney(Float amount)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   347
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   348
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   349
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   350
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   351
                Retrieving the current time in the home and local cities:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   352
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   353
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   354
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   355
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   356
[DateTime] Engine.getHomeTime(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   357
[DateTime] Engine.getLocalTime(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   358
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   359
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   360
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   361
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   362
                The DateTime object returned by getHomeTime() and getLocalTime() is a JavaScript
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   363
                object that contains the following properties: year, month, date, day, hours, minutes,
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   364
                seconds, timezone. All properties are integers except the timezone, which is a string
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   365
                that represents the timezone code, e.g. "EET" for "Eastern European Time". Month and 
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   366
                day are zero-based to simplify their use as indexes in arrays that contains the month
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   367
                and week day names. These arrays can be found in the DateTime object. The array for
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   368
                week day names is called dayNames and the array for month names is called monthNames.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   369
                Day 0 is Sunday and month 0 is January. To find out the name of the day represented
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   370
                by a DateTime object you would do the following:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   371
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   372
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   373
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   374
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   375
var homeTime = engine.getHomeTime();
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   376
var dayOfWeekName = homeTime.dayNames[homeTime.day];
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   377
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   378
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   379
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   380
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   381
                Note that the default JavaScript Date object is not used because of its timezone-
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   382
                related limitations.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   383
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   384
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   385
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   386
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   387
                Retrieving 5-day forecasts for the home and local cities:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   388
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   389
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   390
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   391
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   392
[Array] Engine.getHomeWeather(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   393
[Array] Engine.getLocalWeather(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   394
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   395
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   396
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   397
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   398
                The array returned by the getHomeWeather() and getLocalWeather() methods contains
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   399
                the weather for the next five days so that the first element is the weather today,
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   400
                the second is the weather tomorrow, etc. Each item is a JavaScript object that
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   401
                has two properties: temperature, which is an integer in the preferred temperature
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   402
                unit, and type, which is a string that describes the weather. The type string is
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   403
                one of the following: "Sunny", "PartlyCloudy", "Cloudy", "Rain", "Sleet" or Snow".
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   404
                There is a weather type image for each of these, named so that there is a "Weather"
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   405
                prefix in front of the weather type and a ".png" suffix after it, e.g. "WeatherSunny.png".
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   406
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   407
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   408
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   409
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   410
                Retrieving an array of the latest news headlines:
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   411
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   412
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   413
<pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   414
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   415
[Array] Engine.getNewsHeadlines(void)
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   416
</pre>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   417
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   418
            <p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   419
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   420
                Each item in the array that the getNewsHeadlines() method returns is a JavaScript
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   421
                object that describes one news headline. Each news headline object has two
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   422
                properties: headline for the actual news headline text and url for the website
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   423
                address where the full news article is located.
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   424
            </p>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   425
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   426
        </div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   427
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   428
    </div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   429
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   430
<div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   431
<div class="familylinks">
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   432
<div class="parentlink"><strong>Parent topic:</strong> <a href="WRTKit_Travel_Companion_Tutorial-GUID-be79ba64-fa03-4968-964e-d7dcc42d7053.html">Travel Companion</a></div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   433
</div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   434
</div>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   435
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   436
</body>
41890dfa56f5 Fixed 2046 - added support for WRTKit help
tasneems@symbian.org
parents:
diff changeset
   437
</html>