--- a/org.symbian.wrttools.doc.WRTKit/html/WRTKit_Travel_Companion_planning_the_widget-GUID-891068c7-c802-4da7-8674-8e8292aef7eb.html Fri Mar 05 19:11:15 2010 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,437 +0,0 @@
-<?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">
-<html lang="en" xml:lang="en">
-<head>
-<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
-<meta name="copyright" content="(C) Copyright 2005" />
-<meta name="DC.rights.owner" content="(C) Copyright 2005" />
-<meta content="concept" name="DC.Type" />
-<meta name="DC.Title" content="Planning the widget" />
-<meta scheme="URI" name="DC.Relation" content="WRTKit_Travel_Companion_Tutorial-GUID-be79ba64-fa03-4968-964e-d7dcc42d7053.html" />
-<meta content="XHTML" name="DC.Format" />
-<meta content="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB" name="DC.Identifier" />
-<meta content="en" name="DC.Language" />
-<link href="commonltr.css" type="text/css" rel="stylesheet" />
-<title>
-Planning the widget</title>
-</head>
-<body id="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB"><a name="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB"><!-- --></a>
-
-
-
- <h1 class="topictitle1">
-Planning the widget</h1>
-
- <div>
-
- <div class="section"><h2 class="sectiontitle">
-Designing the user interface</h2>
-
-
- <p>
-
- Because the Travel Companion is such a complex widget it is important to plan
- both the user interface and implementation carefully before starting to write
- any code. What are the most common use cases that we want to address with this
- widget? How will typical users be using the widget? What kind of future features
- might there be and can we plan for those already?
- </p>
-
- <p>
-
- Because the Travel Companion widget offers so much functionality and information
- it is important to present it in such a way that it doesn't overwhelm the user.
- To give the user a better idea of what is available and how to get to everything,
- we'll have a main view with nothing but navigation buttons to the other views in
- the widget. We'll implement this view using WRTKit NavigationButton controls and
- we will give each button its own icon so that the user can quickly see what the
- view is about.
- </p>
-
- <p>
-
- After some planning and talking to potential users we have decided to create
- a summary view that we will call "information view". This view will include the
- most important information in a single place so that the user can view it quickly
- without having to press any buttons to navigate around the widget. We'll put a
- world clock here, the current weather at home and at the local destination, and
- the latest news headlines. The information view will be entirely composed from
- WRTKit ContentPanel controls.
- </p>
-
- <p>
-
- In addition to the information view we'll have two more specialized views. We'll
- have a currency converter with two TextField controls (one for the home currency
- and one for the local) and two FormButton controls. One button will convert
- from the home currency to local currency and the other button will convert in the
- other direction. The second specialized view is a five day weather forecast. Like
- the information view this will be using ContentPanel controls and we will share
- the weather content used for the information view for this view.
- </p>
-
- <p>
-
- Finally we'll have a settings view that is accessible from the main view just like
- the other views in the widget. In many other widgets we might want to hide access
- to the settings view to the Options menu but in this case one of the common use
- cases is to configure where in the world you are so rather than hiding access to
- the view we want to present it clearly in the main view. The settings view will
- use SelectionMenu controls to allow users to select their home and local cities,
- SelectionList controls with a single option that will be presented as a checkbox
- to configure whether the cities are in daylight saving time or not, and a
- SelectionList control that lets the user select the temperature unit to use in
- the weather forecasts. Finally there will be two FormButton controls to let the
- user save or cancel any settings changes.
- </p>
-
- <p>
-
- When the widget starts will setup a timer that will call a timer callback function
- once every second. In the callback function we will check what view is currently
- active and we'll update the views (e.g. clock) so that the views stays up to date
- even if the user doesn't do anything. After all, the most common use case is to
- just have the information view open and not do anything other than glance at the
- information that is displayed.
- </p>
-
- </div>
-
- <div class="section"><h2 class="sectiontitle">
-Travel Companion widget files</h2>
-
-
- <p>
-
- All the files - HTML, CSS, JavaScript and images - have been created for you.
- You can find the completed widget with all its files in the Examples/TravelCompanion
- directory in the WRTKit SDK. The tutorial will assume that you will create your
- own Travel Companion widget by following the instructions but if you prefer you can
- just open up the ready made files and examine them as you read the tutorial. If you
- are creating the widget from scratch by following the tutorial's instructions then
- we suggest that you create a working directory for the new widget and copy over all
- other ready made files except TravelCompanion.js. All of our work will be on this
- file, but before we move on to that file we'll take a look at what other files the
- widget is using.
- </p>
-
- <p>
-
- Since we're using the WRTKit to implement our user interface we have the WRTKit
- library with all its files in a directory called "WRTKit".
- </p>
-
- <p>
-
- Like all widgets the Travel Companion has an Info.plist widget metadata file and an
- icon in a file called Icon.png. You'll also notice that there's a bunch of png
- image files in the widget directory. There's a file called ListViewCaptionLogo.png
- that we will use as a custom graphical element in the view caption in all of our
- views. Four png files have names starting with "Nav" and the rest start with
- "Weather". The image files that have names starting with "Nav" are icons for the
- NavigationButton controls for the main view. They are simply images that are
- 30 by 30 pixels in size and have some graphical motif that captures what the button
- does. Note that the size of images used for navigation buttons doesn't have to be
- exactly 30 by 30 pixels - you can use any size you like. The images with names
- starting with "Weather" are images used in the weather forecasts. There is one image
- for each kind of weather that can be forecasted: rain, snow, sunshine, clouds, etc.
- </p>
-
- <p>
-
- You'll find two JavaScript files: Engine.js and TravelCompanion.js. The Engine.js
- file has the implementation of the business logic and the TravelCompanion.js file
- implements the widget and its user interface. Finally there is the main widget HTML
- file called TravelCompanion.html and a CSS file called TravelCompanion.css that
- contains all the style rules used in the widget - above that what the WRTKit defines
- by default, which is actually nearly everything!
- </p>
-
- <p>
-
- Let's take a quick peek at TravelCompanion.html:
- </p>
-
-<pre>
-
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <title></title>
- <script type="text/javascript" src="WRTKit/WRTKit.js"></script>
- <script type="text/javascript" src="Engine.js"></script>
- <script type="text/javascript" src="TravelCompanion.js"></script>
- <style type="text/css">
- @import url("TravelCompanion.css");
- </style>
- </head>
- <body onload="init()">
- </body>
-</html>
-</pre>
-
- <p>
-
- If you've gone through the Hello World and/or RSS Reader tutorials then this should
- look very familiar. The file has no content, includes the WRTKit.js file from the
- WRTKit library directory, includes the JavaScript files that we are using to implement
- the Travel Companion widget, includes the TravelCompanion.css stylesheet file, and
- finally calls a function called init() when the widget has loaded everything.
- </p>
-
- </div>
-
- <div class="section"><h2 class="sectiontitle">
-The Travel Companion Engine</h2>
-
-
- <p>
-
- Following good software engineering principles, we are implementing the Travel Companion
- widget so that the user interface is decoupled from the implementation of the actual
- business logic that knows weather forecasts, calculates currency conversions, etc. The
- logic is outside of the scope for this tutorial since we're interested in learning about
- how to use the WRTKit - not how to convert euros to dollars. Because of this we will not
- look at all at how the business logic is implemented but we will take a close look at
- the interface between the user interface and the business logic engine. In fact, the
- implementation of the engine for this example is a mock implementation and only mimics
- what a real engine would do. But since this is only an example that's quite alright.
- The engine interface, however, is identical to what it would be even if the engine would
- have a real implementation.
- </p>
-
- <p>
-
- The engine is implemented as a JavaScript class that you instantiate before using.
- The reason for being implemented as a class is simply so that the engine can better
- encapsulate its internal data and provide a kind of name space for its methods.
- </p>
-
- <p>
-
- The core concept in the Travel Companion engine is that of cities. The engine supports
- a list of cities and one will always be a "home city" and one a "local city". The
- same city can be both home and local. Home refers to the city where the user lives
- and local refers to the city where the user is currently located. The engine doesn't
- know the daylight saving time schedules for cities so this is configured manually by
- the user: one setting for the home city and one for the local city. The engine handles
- all preferences but the user interface must tell it to save preferences if some
- preference is modified. Preferences are automatically loaded when the engine is
- created, which should happen when the widget starts so that all the settings are
- available immediately.
- </p>
-
- <p>
-
- A city in the engine is a JavaScript object. A city object has the following public
- properties: name for the city name, currency for the three-letter currency abbreviation,
- and timezone for the timezone code (e.g. GMT). Cities are created and managed entirely
- by the engine.
- </p>
-
- <p>
-
- Below is a complete list of the public engine APIs that are related to preferences and
- cities:
- </p>
-
- <p>
-
- Loading and saving preferences:
- </p>
-
-<pre>
-
-[void] Engine.loadPreferences(void)
-[void] Engine.savePreferences(void)
-</pre>
-
- <p>
-
- Retrieving all cities supported by the engine:
- </p>
-
-<pre>
-
-[Array] Engine.getCities(void)
-</pre>
-
- <p>
-
- Retrieving a city based on its name:
- </p>
-
-<pre>
-
-[City] Engine.getCityByName(String name)
-</pre>
-
- <p>
-
- Retrieving and settting the home city:
- </p>
-
-<pre>
-
-[City] Engine.getHomeCity(void)
-[void] Engine.setHomeCity(City city)
-</pre>
-
- <p>
-
- Retrieving and settting the home city daylight saving time setting:
- </p>
-
-<pre>
-
-[Boolean] Engine.getHomeCityDST(void)
-[void] Engine.setHomeCityDST(Boolean dst)
-</pre>
-
- <p>
-
- Retrieving and settting the local city:
- </p>
-
-<pre>
-
-[City] Engine.getLocalCity(void)
-[void] Engine.setLocalCity(City city)
-</pre>
-
- <p>
-
- Retrieving and settting the local city daylight saving time setting:
- </p>
-
-<pre>
-
-[Boolean] Engine.getLocalCityDST(void)
-[void] Engine.setLocalCityDST(Boolean dst)
-</pre>
-
- <p>
-
- Retrieving and setting the preferred temperature unit:
- </p>
-
-<pre>
-
-[String] Engine.getTemperatureUnit(void)
-[void] Engine.setTemperatureUnit(String unit)
-</pre>
-
- <p>
-
- Of course the engine isn't just about preferences. Its actual purpose is to perform
- various operations related to these cities, such as converting currencies, figuring
- out what the time is in a foreign city, etc. To simplify the usage of the engine,
- the public methods related to these operations are defined in terms of the home and
- local city as it is configured at the time when the method is called.
- </p>
-
- <p>
-
- Here's the full list of the actual operation methods that the engine supports:
- </p>
-
- <p>
-
- Currency conversions between home and local:
- </p>
-
-<pre>
-
-[Float] Engine.convertHomeToLocalMoney(Float amount)
-[Float] Engine.convertLocalToHomeMoney(Float amount)
-</pre>
-
- <p>
-
- Retrieving the current time in the home and local cities:
- </p>
-
-<pre>
-
-[DateTime] Engine.getHomeTime(void)
-[DateTime] Engine.getLocalTime(void)
-</pre>
-
- <p>
-
- The DateTime object returned by getHomeTime() and getLocalTime() is a JavaScript
- object that contains the following properties: year, month, date, day, hours, minutes,
- seconds, timezone. All properties are integers except the timezone, which is a string
- that represents the timezone code, e.g. "EET" for "Eastern European Time". Month and
- day are zero-based to simplify their use as indexes in arrays that contains the month
- and week day names. These arrays can be found in the DateTime object. The array for
- week day names is called dayNames and the array for month names is called monthNames.
- Day 0 is Sunday and month 0 is January. To find out the name of the day represented
- by a DateTime object you would do the following:
- </p>
-
-<pre>
-
-var homeTime = engine.getHomeTime();
-var dayOfWeekName = homeTime.dayNames[homeTime.day];
-</pre>
-
- <p>
-
- Note that the default JavaScript Date object is not used because of its timezone-
- related limitations.
- </p>
-
- <p>
-
- Retrieving 5-day forecasts for the home and local cities:
- </p>
-
-<pre>
-
-[Array] Engine.getHomeWeather(void)
-[Array] Engine.getLocalWeather(void)
-</pre>
-
- <p>
-
- The array returned by the getHomeWeather() and getLocalWeather() methods contains
- the weather for the next five days so that the first element is the weather today,
- the second is the weather tomorrow, etc. Each item is a JavaScript object that
- has two properties: temperature, which is an integer in the preferred temperature
- unit, and type, which is a string that describes the weather. The type string is
- one of the following: "Sunny", "PartlyCloudy", "Cloudy", "Rain", "Sleet" or Snow".
- There is a weather type image for each of these, named so that there is a "Weather"
- prefix in front of the weather type and a ".png" suffix after it, e.g. "WeatherSunny.png".
- </p>
-
- <p>
-
- Retrieving an array of the latest news headlines:
- </p>
-
-<pre>
-
-[Array] Engine.getNewsHeadlines(void)
-</pre>
-
- <p>
-
- Each item in the array that the getNewsHeadlines() method returns is a JavaScript
- object that describes one news headline. Each news headline object has two
- properties: headline for the actual news headline text and url for the website
- address where the full news article is located.
- </p>
-
- </div>
-
- </div>
-
-<div>
-<div class="familylinks">
-<div class="parentlink"><strong>Parent topic:</strong> <a href="WRTKit_Travel_Companion_Tutorial-GUID-be79ba64-fa03-4968-964e-d7dcc42d7053.html">Travel Companion</a></div>
-</div>
-</div>
-
-</body>
-</html>
\ No newline at end of file