samsung mobile widget development guide 1-3-1

7/31/2019 Samsung Mobile Widget Development Guide 1-3-1

1/69

Last updated: 10.05.2010

Samsung Mobile Widget SDK

Samsung Mobile Widget Development Guide

1.0 - About This Document

The Samsung Mobile Widget SDK helps you develop widgets for Samsung mobile devices running the TouchWiz user interf a

This document, t he Samsung Mobile Wi dget Development Guide, i nt roduces you t o the capabil it ies of t he SDK and explains

to use i t to quickly create wi dgets that run on a wide var iety of TouchWiz devices.

The documentat ion is d ivided into t he fo l l owing sect ions:

About This Document - The section you are looking at now, which includes a brief introduction, release notes, and

copyright not i f icat ions.

Introducing the Samsung Mobile Widget SDK - Describes how t o install, update, and launch t he SDK.

The Widget Perspective - Describes t he user int erf ace of t he Samsung Mobile Widget SDK and describ es how t o cust omi

i t .

Creating a Widget Project - A sim ple guide to cr eati ng a proj ect t hat you can use to quick ly produce w idgets for Samsu

TouchWiz devices.

Support ing Mult iple Devices wit h Overr ides - Using one widget proj ect t o support m any dif ferent devices by put t ing

custom ized f i les in overr ide director ies.

Tutorial Sample - A simple widget that uses JavaScript, CSS, and images.

Debugging Widget Proj ects - How to use publicly available debugging tools to f ind errors in your projects.

Widget-Development Tips - Techniques and suggest ions that w ill help you get t he most out of t he SDK.

Developing for BONDI - How t o create w idgets that use t he BONDI fram ework f or gaining access t o device-based

funct ional i ty.

SDK Menu It ems - A refer ence to t he menu it ems that are specif ic t o the Samsung Mobil e Widget SDK.

For installation instructions, see Inst all ing Java and Ecli pseand Inst all ing t he Samsung Mobile Wi dget

SDK.

The Eclipse IDE for JavaScript Web Developers is the ideal Eclipse version for using the Samsung Mobile

Widget SDK. Either t he Eclipse IDE for Java Developers or the Ecli pse IDE for Java EE Developers wi l la lso work. I f you insta l l the Eclipse IDE for Java Developers, several addit ional component s (such as t he

WTPWeb Tools Platform) are al so install ed when you install t he Samsung Mobile Widget SDK. For mor e

informat ion, see Ecli pse Requir ement s.


2/69

1.1 - Document Version History

Vers ion Dat e Not es

0.1 06-25-2009 Draft version

1.0 08-04-2009 First Release

08-10-2009 Reformatting

08-14-2009 New update site URL

08-20-2009 Modify tutorial, add platform release note

1.0.1 09-25-2009 Automatic update site addition, new device.

1.1 12-31-2009 Numerous product updates, including auto-export, transparency support, seller site

integration, and UI improvements.

1.2 04-28-2010 Implementation of BONDI emulation and the addition of the BONDI-enabled Wave device.

This release is final on 04-28-2010.

1.3 08-20-2010 Integrated widget debugging.

1.3.1 09-15-2010 Updated BONDI section. The revisions clarify that the bondi.devicestatusmodule isnot available to widget developers. Also updated the discussion of Eclipse requirements to

mention the Ecl ipse IDE for JavaScr ipt Web Developers.

1.2 - Release Notes

This section lists issues that are specific to recent releases of the Samsung Mobile Widget SDK.

1.2.1 - Version 1.3 Update

The foll owing feat ures have been added for ver sion 1.3.

Integrated debugging: Discussed in Debugging Widget Proj ects.

Updated Eclipse requirement t o version 3.6, "Helios.": Discussed in section 2.0 - Instal li ng Java and Ecli pse.

Windows 7 support : Th e Samsung Mobil e Widget SDK is now suppor t ed on Win dow s XP and Window s 7.

Breakpoints in init ialization code may be missed when launching the debugger. To force a stop at a breakpoint during

in it ia l izat ion, r i ght cl ick on the emulat or and choose Reload.

The fo l lowing modif icat ions were m ade to the documentat ion for version 1.3.1:

bondi.devicestatus: The bondi.devicestatusmodule is not avai lable t o widget developers.

Eclipse IDE for JavaScript Web Developers: This new version of the Eclipse IDE is ideal for using the Samsung Mobile

Widget SDK.



BONDI emulat ion: Widget s can be created t hat ut il i ze the new capabilit ies of BONDI-enabled devices. Discussed in

Developing for BONDI.

New device: The Wave, a new ly r eleased BONDI-enabled device, has been added t o t he Device List .

Updated Java requirement t o version 6: Discussed i n secti on 2.0 - Inst all ing Java and Ecli pse.


3/69



ACCESS NetFront browser is now emulated: Discussed in section 4.5 - Previ ewi ng a Widget Proj ect.

Right-cli ck (Context ) menu: There are four new i tem s in the context menu:

r Add Device adds a device to the Device List. Ment ioned in the note in sect ion 4.2 - Select ing Devices.

r Package creat es a .WGT f i l e . Ment ioned in sect ion 4.6 - Packaging a Widget.

r Update Proj ect ensures that t he current XML schema for your p roj ect i s up to dat e. It may be necessary t o use thi s

menu it em w hen you import a proj ect t hat w as creat ed wit h an earl ier version of t he Samsung Mobile Widget SDK. M

users wi l l not use t h is menu i tem.

r Applicati on Store causes your defaul t brow ser t o open a window t o the Samsung Applicat ion St ore, where you can

upload your new widget. Ment ioned in sect ion 4.6 - Packaging a Widget.

Widget Menu item: A new menu item has been added, with the same selections as are listed above for the right-click

(cont ext ) menu. This menu it em m ay not be visible t o users who are upgrading fr om previ ous versions of t he SDK unt il t

reset t he perspect ive (by choosing Window > Reset Perspecti ve) .

Improvements to widget-bui lding rout ines: Refinements include auto-export to f o lder in proj ect and improved naming

packaged f il enames. These im provement s are di scussed in sect ion 4.6 - Packaging a Widget. In previous releases this

secti on was named Export ing a Widget; the "export" f unct ional i ty has been replaced wit h "packaging."

Relaxed Java dependencies: Java and Eclipse requir ement s are di scussed in a new secti on, 2.0 - Inst all ing Java and

Eclipse.

Proxy support : A new, simpler procedure for configuring proxy support is documented in section 8.4 - Using a Proxy Ser

Users of earli er ver sions of t he SDK should rem ove any syst em-w ide envir onment variables or brow ser-specif ic proxy

sett ings that were specif icall y set f or pr evious versions of t he Samsung Mobile Widget SDK:

r To reset the system -wide environment var iable, open Cont rol Panel > System , c l ick the Advanced tab, and cl ick th

Environment Variables but ton .

r To reset proxy sett ings in Opera, go to Tools > Pref erences, c l ick the Advanced tab, open the Network node, and

c l ick the Proxy Server s but ton .

r To reset proxy sett ings in Safari, go to Edit > Preferences, select Advanced, c l ick the Change Set t ings butt on unde

Proxies, and cl ick the LAN Settings but ton .

r To reset pr oxy set t ings in Firefox, go to Tools > Opt ions, c l ick the Advanced tab , c l ick the Network tab, and cl ick t

Settings button in the "Connection: Configure how Firefox connects to the Internet" section.

New devices: Newly rel eased TouchWiz devices have been added t o t he Device List.

Transparent backgrounds: Transparency is support ed on all of t he brow sers used by t he Samsung Mobile Widget SDK. T

NetFront em ulat or supports only 100% t ransparency. This is ment ioned in secti on 4.5 - Previ ewi ng a Widget Proj ect.

Improved error handling: A dialog box warning about errors is displayed when previewing or packaging a project with

errors. Discussed in section 4.5 - Previ ewi ng a Widget Proj ect.

Double-click on device launches preview : This is ment ioned several t im es in t he document. The f i rst ment ion is in sec

4.5 - Previ ewi ng a Widget Proj ect.

New fields in XML files: I t is possible t o add , , and tags t o project.xml. This is ment io

in Edit ing Project .xml.

Access Network emulation: When you uncheck the Access Network check box in t he Creat e a Widget Project dialog b

your new w idget does not have networ k capabilit ies when it i s run on a device. St art ing wit h thi s version of t he Samsun

Mobil e Widget SDK, the devi ce emulat ors used during preview s disable net work capabil it ies when Access Network is not

checked. In previous versions, the em ulat ors ignored t he st ate of t his check box.

Other ref inement s, w hich may not have been ment ioned in t h is l ist , are noted elsewhere in t h is document.
http://-/?-http://-/?-


4/69

1.2.4 - Version 1.0.1 Update

The foll owing feat ures have been added t o version 1.0.1.

Automatic Update Site: A new update sit e has been creat ed for t he Samsung Mobile Widget SDK. It is: http://widge

samsungmobile.com/sdk/. Current users just need t o perfor m an update using t heir cur rent update sites. Choose

Help > Check for Updates. As part of insta l l ing the 1.0.1 update, the l ist of update si tes in Preferences > Install/Upda

Available Software Sites wi ll aut omat icall y be updated t o point t o the new Samsung Mobile Widget SDK updat e sit e at

widget.samsungmobile.com. Future updates wi l l t hen come f rom t he new sit e. Use of t he update si te at

innovator.samsungmobile.com site is now deprecated.

Device List : The GT-M8910 Pixon12 device has been added to t he device list.

1.2.5 - Notes for Beta Users

I f you wer e a beta user of t he Samsung Mobile Wi dget SDK, you w ill need t o uninst all your b eta ver sion befor e install i ng the

current version. To do th is, c lose t he widget perspect ive and t hen fo l low the i nstr uct ions at Uninst all ing t he Samsung Mobil

Wid get SDK.

I f you have used earlier versions of t he Samsung Mobile Wid get SDK, you wil l need t o make some modif icat ions to preexisti n

widget pr oject s. Your best course of act i on is to create a new proj ect and t hen copy f i les and set t ings f rom the preexist ingproj ect in t o the new one.

The generic XML f i le , configinfo.xml, is now named project.xml. You wi l l need to copy set t ings f rom your o ld

XML f i le in to the project.xml fo r your new pro ject .

Th e overrides director i es were named by t he screen resolut ion of t he device, but now t he names are a combinat ion

the r esolut ion and browser name. You wil l need t o copy f i les f rom any older overrides directory into the appropriate

overrides directory in your new project .

1.2.6 - Workspace Setup

Please verif y t hat your w orkspace is set up t o use UTF-8 as t he default t ext encoding.

1. Select Window > Preferences > General > Workspace

2. Cl ick t he Other radio but ton in the Text file encoding section and select UTF-8 from the drop-down list.

1.2.7 - JavaScript Support

Preferences are in Window > Pref erences > JavaScri pt

Do not manual ly add or remove l ibrar ies f rom your project . L ibrar ies wi l l be bet ter supported in a fut ure re lease.

Until further notice, do not select "Enable JavaScript semantic validation" (see Window > Preferences > Web > JavaSc

> Validator > Errors/Warnings). Select ing t his option cur rent ly pr oduces some spurious errors and w arnings.

I f you prefer not to be warned about missing semicolons, do the following:

1. Select Window > Preferences

2. Expand Web > JavaScri pt > Validator

3. Select Errors/Warnings

4. Check "Enable JavaScript semant ic validat ion"

5. Expand "Potent ial programming problems"

6. Change "Opti onal Sem i-Colon" to "Ignore"

7. Turn off "Enable JavaScrip t semant ic validati on"

8. Cl ick the OK button. Select Yes when asked about a fu l l rebui ld.


5/69

1.2.8 - Run As Widget

I f you see a Windows error dialog box when you use the Run As > Widget comm and, you m ight b e mi ssing some VisualSt udio

runt im e l ibrar ies. Download and insta l l them here.

Current ly Run As Widget is unsupport ed on Mac OS X or Linux. To run your wi dget on Mac OS X or Linux, f ollow t he instruct

for r unning wit h a browser in the Widget Development Tips secti on. See: Previ ewing on a Browser

Watch for future updates to the Samsung Mobile Widget SDK for your favorite platform.

1.3 - Help System

I f you are reading this document in the form of a PDF file, you might prefer to use the integrated help system in the Samsun

Mobil e Widget SDK. The help syst em incl udes a persistent menu t ree, a robust search facili t y, bookmar king capabilit ies, and

easy access to a wealt h of Eclipse document ati on.

In the Widget per spect ive, choose Help > Help Contents.

Use the Content s view t o navigat e to Samsung Mobile Widget Development Guide.

1.4 - Copyright NotificationsAny company and product names not expl ic i t ly m ent ioned below m ay be t rademarks of t he respect ive companies wit h whic

t hey are associated.

Samsung Electronics

This materi al is copyrighted by Samsung Elect ronics. Any unaut horized repr oducti ons, use or disclosure of t his mater ial, or a

part thereof, is strict ly prohibited and is a violation under the Copyright Law. Samsung Electronics reserves the right to mak

changes in specif ications at any t ime and without notice. The information furnished by Samsung Electronics in this material

bel ieved to be accurate and re l iable, but is not warranted t rue in a l l cases.

"SAMSUNG", "SAMSUNG.com" and "SAMSUNG DIGITall Everyone's invited" are trademarks of SAMSUNG in the United States or

other countr ies. Unauthorized use or dupl i cat ion of these marks is str ict l y prohib it ed by law.

The Samsung Logo is the trademark of Samsung Electronics.

Eclipse Foundat ion, Inc.

Eclip se is a tr ademark of Eclipse Foundati on, Inc. Copyright 2005, 2009. All r ight s reserved.

Firefox

Firefox Copyright 1998-2009 Contr ibut ors. All r ight s reserved. Firefox and t he Firef ox logos are t rademarks of t he Mozill aFoundation. All r ights reserved.

Microsoft Corporation

Windows is a regist ered t rademark of Microsoft Corporat ion in t he United St ates and ot her countr ies.

NetFront

Copyri ght 2009, ACCESS CO. , LTD.

ACCESS and NetFront are trademarks or registered trademarks of ACCESS Co., Ltd. in Japan and other countries.
http://www.microsoft.com/downloads/details.aspx?familyid=200B2FD9-AE1A-4A14-984D-389C36F85647&displaylang=enhttp://-/?-http://-/?-http://www.microsoft.com/downloads/details.aspx?familyid=200B2FD9-AE1A-4A14-984D-389C36F85647&displaylang=en


6/69

Opera

Copyright 1995-2009 Opera Software ASA. All rights reserved.

Safari

Copyright 2007-2009 Apple Inc. All r ight s reserved.

Sun Microsystems, Inc.Java is a tr ademark of Sun Microsyst ems, Inc.

WebKit , Apple, and JavaScriptCore

The WebKit Open Source Proj ect ( includi ng port ions fr om t he khtm l, kcanvas, kdom , and ksvg2 proj ect s) and JavaScript Core

Project (incl uding port ions from t he kj s proj ect) Copyright 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,

2007, 2008, 2009

All cont ent s Copyright Samsung Elect ronics Co., Ltd .


7/69



Int roducing the Samsung Mobile Widget SDK

The Samsung Mobile Widget SDK is a widget -developm ent environm ent based on t he Eclip se open development p l at form .

Samsung Mobile Widget SDK helps you develop widgets for Samsung mobile devices running the TouchWiz user interf ace.

This guide shows you how t o create a widget proj ect , launch the widget on t he device emulator, and package i t for r e lease

addit ion, you will f ind a step-by-step description of creating a sample widget that answers many common questions about

widget development.

Samsungs TouchWiz user int erf ace includes 3D-eff ect s, hapt ic f eedback, and gest ure and voice control s. The TouchWiz wid

dock makes it easy for custom ers to manage and download wi dgets that custom ize and personalize t heir devices.

Samsung Mobile Widget SDK sim plif ies the t ask of developing w idgets in a num ber of ways:

I t uses t empl ates to creat e proj ect s you can use as a st art ing point.

I t provides an emulator that makes i t easy t o visual ize the f i nal product on mult ip le devices, br owsers, and plat form s.

I t simplif ies the customization of widgets for different sizes of device screens.

I t provides IDE features like autocomplete, context menus, and error tracking.

I t im ports exist i ng widgets, enabl ing you t o examine and modif y t hem.

I t packages widgets for distribution.

The Samsung Mobile Widget SDK is current ly support ed on Window s XP and Window s 7. It bundles browser li brari es to cl osel

emul ate t he dif fer ent m obile br owsers used on Samsung devices.

This guide assumes that you have some familiarity with Eclipse and that you are familiar with HTML, CSS, and JavaScript.

2.0 - Installing Java and Eclipse

You will need at least version 6 of t he JRE and t he Helios release (version 3.6) of Eclipse t o install t he Samsung Mobile Widg

SDK.

2.0.1 - Java Requirements

You will need t he JRE (Java Runti me Environment ) version 6 or higher t o use t he Eclipse IDE. You wi ll somet im es see t his

ref erred t o as Java version 1.6. To download Java, visit : http://java.com/. For more inform at ion, see: http://www

eclipse.org/downloads/moreinfo/jre.php

You m ust have Java Version 6 to run t he Samsung Mobile Widget SDK. If you i nst all it using Java 5, t he

Widget perspect ive wi l l not be avai lable.
http://java.com/http://www.eclipse.org/downloads/moreinfo/jre.phphttp://www.eclipse.org/downloads/moreinfo/jre.phphttp://www.eclipse.org/downloads/moreinfo/jre.phphttp://www.eclipse.org/downloads/moreinfo/jre.phphttp://java.com/


8/69

2.0.2 - Eclipse Requirements

The Helios release of Eclip se (version 3.6 or higher) is requir ed t o run t he Samsung Mobile Widget SDK. The Eclipse IDE for

JavaScript Web Developers is the ideal Ecli pse version f or using t he Samsung Mobile Widget SDK. Either t he Eclipse IDE for

Java Developers or the Eclipse IDE for Java EE Developers wil l a lso work. I f you start wit h Ecli pse IDE for Java Developer

the installation routine for the Samsung Mobile Widget SDK automatically downloads addit ional features that you need,

assuming t hat t he http://download.eclipse.org/releases/heliosupdate sit e is present and enabled in Ecli

I f you are using the Ecli pse IDE for Java Developers and you have t rouble install i ng the Samsung Mobil e Widget SDK, ensure

that this update site is present and then restart Eclipse.

When you upgrade to a new version of Eclipse, you can specify t hat t he new ver sion should use your previous Eclip se

workspace. This ensures that your previous proj ects wi l l appear wit hout your having to m anual ly i mport them into a new

workspace.

To download Eclipse, vi sit : http://www.eclipse.org/downloads/

2.1 - Installing the Samsung Mobile Widget SDK

The Samsung Mobile Widget SDK wid get developm ent environm ent is impl ement ed as a series of Eclipse plug-ins. To i nst all

go to t he Eclipse Help menu and select Install New Soft ware. The Install dialog box appears:

Cl ick t he Add but t on to add t he Samsung Mobile Widget SDK dist ribut ion sit e to your l ist of availabl e soft ware sites. The A

Site dialog box appears:
http://www.eclipse.org/downloads/http://www.eclipse.org/downloads/


9/69

Give the update si te an ident i f iable name in the Name f i eld - somet hing lik e "Samsung Mobil e Widget SDK update sit e" - and

specif y t he URL in the Location field. The URL for the Samsung Mobile Widget SDK update site is:

http://widget.samsungmobile.com/sdk/

Click t he OK butt on when you are f in ished. From the Work with: combo box, select t he update si te t hat you j ust added.

Th e Install dialog box should now di splay "Samsung Mobile Widget SDK" in t he li st of available soft ware:

Select t he checkbox next t o "Samsung Mobil e Widget SDK" and t hen cli ck t he Next but t on. A progress bar across t he bott om

t he wi ndow shows you that Eclip se is "Calculat ing requir ement s and dependencies."

An Install Details screen appears, l ist ing the items to be installed:

Select t he "Samsung Mobile Widget SDK" it em and click t he Next but ton .

Review and accept the license, and click the Finish but ton .

When the "Operation i n progress" progress bar t ells you that t he inst allat ion is f inished, a Soft ware Updates dialog box


10/69

"st rongly recomm ends" that you rest art Eclip se. Click Yes t o foll ow t his suggest ion.

In the f utur e, vari ous language packages wi ll al so be availabl e at t he download sit e. You will downl oad the language packag

as part of t he installat ion procedure i f you w ant t o run t he Samsung Mobile Wi dget SDK in one of t he support ed languages.

2.2 - Updating the Samsung Mobile Widget SDK

Aft er you have enter ed t he Samsung Mobile Wid get SDK inst allat ion site as part of t he inst allat ion procedure, it is easy t o st

up-to-date. Just go to Help > Check f or Updates. Any Samsung Mobile Widget SDK updates wi ll be li st ed in t he Available

Updates dialog box.

If you need t o view or change the Samsung Mobil e Widget SDK update site you have specif ied, go to Window > Pref erences

expand t he Install/Update node, and choose Available Software Sites.

2.3 - Uninstall ing the Samsung Mobile Widget SDK

I f you ever needed t o uninstall t he Samsung Mobile Widget SDK, you would begin by going to Help > About Eclipse SDK and

cl icking the Installation Details but ton .

You should see "Samsung Widget SDK" in t he list on t he Inst alled Soft ware t ab. To uninstall, sim ply select t his item in t he lis

and cl ick the Uninstall but ton .

2.4 - Launching the Samsung Mobile Widget SDK

Aft er you have install ed t he Samsung Mobil e Widget SDK, you can launch it by opening t he new Widget perspective i n Eclip s

To do th is, c l ick t he Open Perspective icon at t he right side of t he Eclipse window and choose Other f rom the bot t om o f

l ist .

Choose "Widget" fr om t he list in t he Open Perspective dialog box and click the OK but ton .

The Widget perspective opens, revealing the views and editors you will use to help build widgets for the TouchWiz interface


11/69



12/69



The Widget Perspective

The Widget perspecti ve in Eclipse looks like t his:

Most of t his is fam ili ar t o experienced Eclip se developers:

Proj ect Explorer view shows you t he names and str uctures of your current pro j ects. Note that widget proj ects are

decorat ed wit h an open fol der cont aining an "S". Source Editor views display the edit able f i les in your proj ect and provide tools for edit ing them.

Outline view gives you an easy way to see the organization of the f i le that is currently open in the editor and allows you

j um p qui ck ly t o gi ve n poi nt in t he f i le.

Device view displays the devices that are emulated when you preview your widget. Enables widget developers to add ne

devices t o their pr o ject s by dragging them into t he project 's Device List.

Instance Management views give you infor mat ion you can use to add devices to your proj ect and diagnose problem s. Ot

views appear here when t hey are invoked; f or exampl e a Search view di splays the results of any search operat ion, and a

Console vi ew displays debugging output .


13/69

3.0 - Customizing a Perspect ive

A perspect ive contains mult ip l e views into t he f i l es that make up your project . The Source Editor views must remain inside

main Eclipse wi ndow, but t he other vi ews can be dragged outside and posit ioned wherever you like. This can give you more

room to work in the Source editors. Move or restore a view by clicking its tab and dragging it to a new posit ion.

To return a perspective to its default appearance, choose Window > Reset perspective.

I f you f ind that you usually modify the default perspective, you can save your preferred configuration by choosing Window

Save Perspect ive as and giving your conf igurati on a unique name. This new perspecti ve now appears among t he choices i

t he Open Perspective dialog box.

You can add views to your per spect ive, i f you l ike. To see a list of views you can add, choose Window > Show View. I f you

choose Other... in t he menu that appears, you wi l l be presented w it h a Show View dialog box t hat gives you access to a l a

number of possibil it ies.

Another common custom izat ion is to use f i l ters to choose which f eatures to h ide and show. For example, you mi ght want to

hide any closed project s in t he Proj ect Explorer view. To close a project , r ight-cl ick t he name of the proj ect in Project

Explorer and choose Close Proj ect f rom the context menu. The icon decorat ing the proj ect name changes f rom an open fo l

to a closed folder.

To hide closed proj ects, c l ick t he View Menu icon in Project Explorer (a small inverted triangle) and choose the Customize

View opt ion.

In the Available Customizati ons dialog box that appears, select the "Closed projects" f i lter in the Filters tab and cl ick t

OK but ton .


14/69



15/69



Creat ing a Widget Project

You can create a new w idget proj ect in j ust a few m inutes.

4.0 - Creat ing a New Project

A widget proj ect is populated w it h the f o lders and f i les you need t o start developing a new widget.

Open the Widget per spect ive, i f you haven't done so already, as described in Launching t he Samsung Mobil e Widget SDK.

Choose Other f rom th is drop-down l ist t o see the Widget perspect i ve.

4.1 - Configuring your Project

Choose File > New > Widget Proj ect . In the Widget Proj ect dialog that appears, specify a name for your p roj ect . You can u

t he default Eclipse workspace or you can specif y a new locati on.


16/69

The conf igurat ion inf ormat ion def ines several import ant t h ings about your w idget.

Description: A br ief descr ipt ion of your widget.

Version: A version number t hat ident i f ies your w idget. This should be in t he form major_version. minor_version.

Widt h and Height: The size, in p ixels, of the w idget when i t appears on the t arget device.

Access Network: Designates whether t he wi dget accesses the net work. The default set t ing is TRUE. You should uncheck

t his box if your wi dget does not t he netw ork, as shown in t he preceding screen shot.

You can edit t hese set t ings lat er, if necessary, by opening t he project.xml f i le in t he root o f your w idget p ro ject .

Th e project.xml f i le i s a generic confi guration f i le t hat t he Samsung Mobile Widget SDK uses to generate t he config.

xml f i l e that is required by t he f in ished widget. Dif f erent versions of t he config.xml f i l e are required for d i f ferent

plat form s. The Samsung Mobile Widget SDK generates t he correct for m of config.xml whenever you package a project,

based on your proj ect 's project.xml f i l e and the plat form of t he target device.

When you have f in ished wit h t h is Creat e a Widget Project screen, cl ick t he Next but ton .

4.2 - Selecting Devices

The next screen in the "Widget Proj ect" wi zard enables you to choose one or more devices for your proj ect:


17/69

You can select more t han one device by using the usual Ctrl+Click and Shift+Click key combi nati ons, as shown in t

preceding screen shot.

You can add new devices to a proj ect at any t ime by dragging them from the Device view to your

project 's Device List node in Proj ect Explorer. Alternat ively, you can r ight-cl ick t he Device

List and ch oose Add Device.

When you have f in ished wit h t h is Select Devices screen, cl ick t he Next but ton .

4.3 - Select ing a Template

In the next dialog box, Select a Template, you can choose betw een a number of t emplates that provide a working foundat i

fo r your w idget p ro j ect .


18/69

This list of t empl ates changes dynamicall y as im provement s are made t o the SDK. The current set of t empl ates may be

dif f erent f rom w hat you see in t h is screen shot.

The "Empt y" and "Hel lo World" t emplates provide simpl e but val id start ing points for your proj ect .

The "RSS Reader" widget im plem ents many good ideas in cr oss-plat for m w idget design. For m ore inf ormat ion, see Best

Pract i ces for Widget Development.

The "BONDI" tem plat es assist BONDI developers get start ed w it h dif fer ent BONDI modules. For m ore inf ormat ion about

BONDI, see Developin g for BONDI.

Choose the "Hello World" template and click the Finish butt on to create your Widget proj ect .
http://-/?-http://-/?-http://-/?-http://-/?-


19/69

4.4 - St ructure of a Widget Project

Your new wi dget proj ect looks l ike th is in the Proj ect Explorer view:

Most of t he f i l es in a new proj ect are start i ng points for your code; as you would expect , t he "Hel lo World" templ ate create

very simple widget.

Device List Lists the t arget devices for your w idget. You can add t o th is l ist af t er you have created t he proj ect by

dragging devices here fr om t he Device view .

JavaScript Resources A read-only list of the libraries that are available to your widget. As you add devices to your

proj ect , l ibrar ies avai lable on that device are automat ical ly added to t h is directory. You can browse thr ough t he l ibrar ie

to l ook for f unct ions or documentat i on on funct ions in the supported l ibr ar ies.

css > style.css List s t he CSS fi les defining t he appearance of your HTML fil e(s). The def ault f i le, style.css, is l inke

at t he top of t he default HTML f i le; you can supply more CSS files in this directory, if necessary, and link to them from

HTML f i le .

images List s the PNG im ages used by your w idget. PNG is the preferr ed f i le f ormat, because PNG f i les support

transparency and have ample color depth.

j s > main. j s Lists the JavaScript f i l es that supply the f unct ional i ty of your widget. The default f i l e , main.js, is spec

at t he top of t he default HTML f i le .

overrides List s groups that defi ne t he screen resolut ions and brow sers support ed by your pr oj ect 's devices. You can us

t hese groups t o cust omize your w idget f or part icular br owsers and resolut ions. In this case, t he 240x400 NetFront

group is for t he Pixon device, and t he 240x400 Opera group is for t he Omnia device. For m ore inform at ion, see

Supporting Mult iple Devices with Overrides.

icon.png An icon that i s displayed in the device s widget t ray to ident i fy your w idget. The size of t he icon var ies with

screen size of t he target device:


20/69

r QVGA (240 x 320) the maximum width of the tray is 56 pixels. A square icon should be no wider than 44 pixels.

r WQVGA (240 x 400) the maximum width of the tray is 60 pixels. A square icon should be no wider than 50 pixels.

r QHD (360 x 640) the maximum width of the tray is 81 pixels. A square icon should be no wider than 65 pixels.

r WVGA (480 x 800) t he maxim um w idt h of t he tr ay is 126 pixels. A square icon should be no wider t han 102 pixels.

index.html Provides t he HTML code that implements the appearance of your widget. Most widgets use only one HTML

f i l e . You might use more t han one HTML f i l e i f your widget were impl emented in mult ip le languages; t he index.html

f i le woul d allow users to choose a language, and each language would be i mpl ement ed in it s own HTML f i le .

project.xml Supplies conf igurat ion inf ormat ion, including the inform at ion you specif ied when you created t he proj ect

you needed t o change a wi dget 's widt h and height , for instance, you w ould need to edit th is f i l e . When you double-cl ick

project.xml, a t abbed edit or appears. The f i rst tab, General, appli es t o all wi dgets. The other t abs apply t o BONDI

widgets. For m ore inform at ion, see BONDI UI Ele me nt s in t he SDK.

Your icon f i le must be named icon.png and your root-level HTML file must be named index.html.

4.5 - Previewing a Widget Project

The simplest way t o preview your new widget is to double-cl ick t he device on which you would l ike t o run the preview i n th

Device List in Proj ect Explorer. There are a number of ot her ways to start a preview, t hough. The complete l ist is:

Double-cl ick the device in t he Device List.

Right- click t he device and choose Run As > Widget .

Click t he small t r iangle next t o the Run icon and choose Run As > Widget .

Use the Run menu: Run > Run As > Widget .

The Samsung Mobile Widget SDK uses t hree dif fer ent em ulat ors to preview your wi dget. A WebKit em ulat or handles t he

previews for devices that use Dolf in. For example, a preview of the "Hello World" widget on the Tocco device looks like this

when t he emulator appears:


21/69

The SDK's second emulator is based on the ACCESS NetFront browser. When you preview your widget on a device that uses

NetFront, a window named NetFront Widget Emulator appears, di splaying the w idget's icon, and t he widget appears on the

skin f or t he chosen device:

The thi rd emul ator i s based on the Opera browser. This emulator is used for Window s Mobil e devices. For example, a previe

of t he "RSS Reader" widget on t he Omnia (Opera) device l ooks like t his when t he emul ator appears:

The RSS Reader widget retrieves headlines from Yahoo! News. The Opera browser runs behind t he emulat ed wid get, as show

above. When you choose one of the stori es in t he list, t he widget displays st ory det ails:


22/69

The back arrow above the story returns the reader to the list of stories. The plus button launches a browser that displays th

fu l l story on the Yahoo! Newssite.

I f t here is an error in your projecti f there are m issing or incorrect ent r ies in your project.xml f i l e , or i f you have

JavaScript error, for examplethe f i le wit h the problem is decorated wi th a red x in Proj ect Explorer. I f you t r y to preview

package a project that contains errors, an Err ors in Project dialog box warns you that you may have overlooked a bug.

Transparency is support ed in all of t he emulat ors, but t he Net Front emul ator support s only 100% t ransparency.

You can use t he Run butt on as a shortcut af ter you have run several w idget previews. When you cl ick t he small arrow t o the

r ight o f the Run but t on ( ) , a li st o f recent launches appea rs. Choose the p rojec t you want t o preview f rom th is l i st .


23/69

4.6 - Packaging a Widget

When you have written and debugged your widget, you are ready to package i t . Packaging a widget pr oject bundles a l l of t h

widget f i les together into a .WGT f i le. The packaged widget includes any customized f i les you may have included in the

project 's overrides directory and a device-specif ic config.xml f i l e t hat t he IDE produces automat ical ly f rom your

project 's project.xml f i le .

Bring up the Package dialog box by doing one of the following:

Right- click a device in your Device List and choose Package f rom the context menu t hat appears. To package yourwidget for m ore than one device at a t im e, select t he root of t he project or t he root of t he Device List and choose

Package f rom the context menu.

Select a device, the Device List node, or the root of t he project , and then either choose the Widget > Package me

it em or use the CONTROL+SHIFT+P key combinat ion.

Th e Package dialog box gives you the opport unit y to ent er a Widget ID for any wi dget you plan t o submi t t o the Samsung

Applicat ion store. This ID appears in t he config.xml f i l e of your packaged widget. Cl ick t he Finish but ton to crea te a .W

f i le f o r your w idget , in the packages directory in Project Explorer.

In thi s exampl e, t he wi dget bei ng packaged for a Corby device has an ID of "1234-9876." When you click Finish, a package

appears in your project 's packages directory:


24/69

A packaged widget is given the name of your proj ect : in t his case "My New Widget.WGT. " You could rename th is f i l e , i f

necessary, by selecti ng the f i le and pressing F2, or by choosing Rename in t he Context or File menus. A .WGT f i l e is real ly

standard compressed f i le w it h a .WGT f i l ename ext ension; t o view i t s contents, you can rename t he f i l e by adding a .ZIP

extension and then open i t wit h any compression ut i l i t y.

Th e config.xml f i le in the .WGT f i l e t hat w as j ust produced includes th is l ine:


25/69


Samsung Mobil e Wid get SDK

Support ing Mult iple Devices wi th Overr ides

5.0 - Developing for Mult iple Devices

The Samsung Mobil e Widget SDK makes it easy to custom ize your wi dget f or dif fer ent d evices. Inst ead of having to cr eate a n

widget proj ect f or each new device, you can use overr idesto custom ize your wi dget .

Whenever you need t o provide a customized f i le in your proj ect - an icon, image, CSS f i le, JavaScr ipt tw eak, HTML f i le , or

project.xml - you should supply i t in one of your pr oject 's overrides director i es. When you preview or package your

proj ect , the IDE automat ical ly picks up the customized f i l es f rom the overrides directory for the target device.

5.1 - Device Groups

Every devi ce you can use in t he Samsung Mobile Widget SDK is a memb er of a group. Groups classif y devices by t heir screen s

and the brow ser t hey support . The Group column in Device v iew gives this informat ion for each device.

Your proj ect 's overrides directory contains a subdirectory for each group t o which your proj ect 's devices belong. For

example, in the following screen shot the project uses f ive devices: a BeatDJ, an Omnia, a Star, and a Tocco. The overrid

directory contains subdirectories for four groups. There are two Dolf in groups - one for the Tocco, whose screen is 240x320,

one for t he Star , w hose screen i s 240x400. The 240X400 NetFront group supports both the BeatDJ and the Pixon device

The Opera group support s t he Omnia.

5.2 - Overr ides

You might choose t o lay out your widget di f f erent l y for di f f erent screen sizes, or to use special-case code for di f f erent brows

You can do this by put t ing modif ied f i l es into t he overrides directory f or a speci f ied group. The f i les at t he root of your

proj ect are used by default w henever you run or package a widget ; i f you put a modif ied f i l e into one of t he overrides

d i rec tor ies, t hat f i le w i l l over r idethe defau l t f i le .

You could use a single w idget proj ect t o support bot h a QVGA (240 x 320) device and a WVGA (480 x 800) device, f or exampl

Let 's say that t he HTML and JavaScr ipt f i l es were t he same for both of t hese devices; the HTML is simp le, and t he JavaScript


26/69

contains any required special-case code f or w indow r esiz ing. In this case, you m ight need t o support the di f f erent screen

resolut ions with customized icon f i les, separate images, dif ferent CSS f i les for posit ioning objects, and separate project.

f i l es containing the s ize of t he widgets. A schemat ic v iew of t he proj ect m ight look somet hing l ike this:

Device List

Device One (240x400)

Device Two (240x320)

Device Three (480x800)

jsmain.js (only JavaScript for this project)

css

style.css (default styles for this project)

images

myimage.png (default image for this project)

overrides

240x320 BrowserA

css

style.css (styles for this smaller resolution)

images

myimage.png (smaller image)

jsicon.png (smaller icon)

project.xml (custom values for width and height of widget)

480x800 BrowserB

css

style.css (styles for this larger resolution)

images

myimage.png (larger image)

js

icon.png (larger icon)

project.xml (custom values for width and height of widget)

icon.png (default icon for this project)

index.html (only HTML for this project)

project.xml (default configuration information for this project)

In this case, whenever you previewed or packaged your widget for Device One, t he IDE would pick up t he default f i les: t he

st yles, im ages, i con, HTML, XML, and JavaScr ipt . When you previewed or packaged the w idget f or Device Two, the IDE wou

bui ld a wi dget using the default HTML and JavaScr ipt , but w ould overr ide the other f i les wit h the contents of the 240x320

BrowserA directory. Simi l ar ly , w hen you previewed or packaged t he widget for Device Three, t he IDE would bui ld a w idget u

the default HTML and JavaScr ipt , but would use t he content s of t he 480x800 Brow serBdirectory.

Example: Overr iding index.html

For example, you could change the index.html f i le f or t he Tocco's small er screen to say "Hello Small er Worl d." Copy and

paste t he project s index.html f i le in to the overrides > 240x320 Dolfin directory (or CTRL + Drag) , ed i t th

t ex t i n t he HTML f i l e, and preview t he result on the Tocco and the other devices. The changes you make to t he f i l es in t he

overrides > 240x320 Dolfin appear only when you preview on the Tocco - t he widget s for t he other devices have n

changed. Note t hat you do not need t o copy any JavaScript or CSS f i les in this case - the onl y f i l e you need to put in t he

240x320 Dolfin directory i s the f i le t hat is changing for t his overr ide.

To preview your widget on a part icular device, double-c l ick t he device in the Device List in Project Explorer .

The output on the Tocco emulator l ooks l ike t his:


27/69


28/69



Tutorial Sample

This section of the Samsung Mobile Widget Development Guide leads you thr ough t he process of creat ing a sim ple w idget. T

wi dget uses sim ple CSS and JavaScript t o animat e but t ons and change the vi sibil it y of paragraphs - it is only slight ly m ore

complicated t han the "Hel lo World" templat e.

6.0 - Create the Project

First , create a widget proj ect , as out l ined in the preceding sect ions. There is one important d i f f erence in the procedure g iv

in t he fo l lowi ng l ist , however. When you create t h is proj ect , you should not use a tem plate as a start ing point .

1. Ensure that you are using the Widget perspect ive.

2. Choose File > New > Widget Proj ect and give your pr oj ect a name. This sample uses the name "Choose_a_Butt on".

Give your proj ect a unique ID and add other confi guration inf orm ati on. For the "Choose_a_But t on" project , use 180px fo

the height and widt h.

Uncheck the Access Network checkbox and click the Next but ton .

3. Select t he Pixon fr om t he list of Devices on the next dialog box and click Finish. Do not cl i ck the Next butt on - we do n

want t o start wit h any of the suppl ied templat es for t h is proj ect .

The "Choose_a_Button" project appears in the Project Explorer view. This project is even simpler than the project created

the "Hel lo World" tem plate; i t has an empty HTML f i le .

When you expand the nodes of t he "Choose_a_But t on" project in Project Explorer view, it should look li ke thi s:


29/69

6.1 - Edit the CSS File

Add a f i le named style.css t o t he css directory, and add t he fo l lowi ng to change t he appearance of any paragraph tex

the widget:

body {

background-image:url(../images/abstract_180x180.png);

}

p {

color:#882222;

font-family:sans-serif;

font-size: medium;

font-weight:bold;

position:relative;

margin-left:20px;

}

.output {

position:absolute;

top:90px;left:0;

}

Th e body secti on loads a background im age, superseding the def ault t ransparent color. The image looks like t his:

Th e p section defines the color, font characterist ics, and posit ion for default paragraphs. The .output class is used t o mo

t he paragraphs t hat appear w hen the user presses a butt on.

6.2 - Create and Import the Images

Creat e PNG fi les for t he images you wil l use as but t ons in t his widget. We need a "Yes" butt on and a "No" but t on. Each but t o

also needs a version that gives t he user f eedback when i t has been select ed.

The four but t ons might l ook l ike th is:

In this example, these buttons are named yes.png, yes_inverted.png, no.png, and no_inverted.png.


30/69

After you have created the but tons, you can drag them from a window in t he f i le system to t he images directory in Project

Explorer to import them into your project .

6.3 - Create and Import the Icon

Creat e a PNG fil e t hat w ill serve as an icon f or t his widget. The screen size of t he Samsung Pixon is given in t he Device view

240 x 400 theref ore, according to t he l ist g iven in St ruct ure of a Widget Proj ect , t he icon should be no wider t han 50 pixe

The new fi le should be named icon.png i f you give it another name, you should change t he icon ent ry in project.xm

to mat ch the new name.

Replace the default icon.png f i l e in t he "Choose_a_Butt on" proj ect w it h your new icon by dragging i t to t he root of the

"Choose_a_Button" project in Project Explorer. Here is one possible icon for the project:

6.4 - Edit the JavaScript File

Creat e a main.js f i le in the js directory.

Th e Choose_a_Button widget creat es tw o but t ons and reacts to user input. The code that animates the but t ons is in the

mouseClick(button) funct i on. Add the fo l lowing to the main.js f i le .

/*=================================================================

* The start() function is called when the onload() event occurs.

* It ensures that the responses to button presses are initially

* hidden.

================================================================*/

function start()

{

document.getElementById("yesreaction").style.visibility="hidden";

document.getElementById("noreaction").style.visibility="hidden";

}

/*=================================================================

* The mouseClick() function is called when the onclick() event

* occurs. It animates the buttons and changes the visibility

* of the paragraphs that display responses to the click.

*

* button parameter - string identifying the button that was clicked

================================================================*/

function mouseClick(button){

if (button=="yesbutton") {

// change the button image for 300 milliseconds

document.yesbutton.src ="images/yes_inverted.png";

setTimeout("document.yesbutton.src ='images/yes.png'",

300);

// ensure other button is in unselected state

document.nobutton.src ="images/no.png";

// change visibility of button responses

document.getElementById("yesreaction").style.visibility="visible";

document.getElementById("noreaction").style.visibility="hidden";


31/69

}

else if (button=="nobutton") {

document.nobutton.src ="images/no_inverted.png";

setTimeout("document.nobutton.src ='images/no.png'",

300);

document.yesbutton.src ="images/yes.png";

document.getElementById("yesreaction").style.visibility="hidden";

document.getElementById("noreaction").style.visibility="visible";

}

else {

document.write("Something went wrong.");

}

}

6.5 - Edit the HTML File

Final ly, you need to edit the index.html f i le so t hat t he widget wi ll use the im ages, CSS, and JavaScript you have j ust p

place.

When the page loads, t he onload event calls the JavaScript start() function to hide the sentences that are displayed

when t he user cl icks a but ton. The but t ons are animated when t he but t ons are cl icked. The onclick event calls JavaScrip

tha t i s imp lemented in the main.js f i le. Finally, the responses to the button clicks are displayed. These output paragraph

use t he output class to ensure that the "yes" and "no" responses appear in the same place.

Would you care to
press a button?

Thank you
for your input.

You are trying
to confuse me.


32/69

6.6 - Preview the Widget

Now that t he im ages, CSS fi le, JavaScript f i le, and HTML f i l e are in p lace, i t is possib le t o preview t he widget. Double-cl ick

Pixon device in the Device List in Project Explorer. The emulator should look l ike t h is:

Use your mouse t o ver i fy t hat t he but t ons animate correct l y and that they handle the m ouse cl icks.

6.7 - Package the Widget

When you are sati sf i ed wit h "Choose_a_Butt on," package it and verif y that it work s successful ly out side t he emulat or. Right

cl ick your target device in the Device List and choose Package. Then fo l low t he direct ions in Packaging a Widget t oproduce a .WGT f i l e and test your widget on your target device.

If you have inst alled t he Opera brow ser, you can test a packaged widget on your comput er.

First , drag a device t hat r uns Opera ( the Omnia, for instance) f r om t he Devices view t o your proj ect 's Device List. Any

wi dget packaged for an Omnia device w ill run on Opera. Right-cl ick t he Omni a device and choose Package.

Double-cl ick t he .WGT f i l e inside the packages directory t o launch the Opera browser, or drag the .WGT f i l e into an Ope

window. Drag the Opera window away f rom t he widget t o ver i fy t hat t he widget is running on your desktop. The fo l lowing

screen shot shows the Create_a_Butt on wid get runni ng on the deskt op:


33/69

To close t he widget, r ight-cl ick i t and choose Close.



34/69



Debugging Widget Proj ects

This secti on of t he document ati on discusses t he debugger t hat i s integrat ed int o t he Samsung Mobile Widget SDK. This

debugger includes most standard debugging functionality, including the ability to start and stop execution, set breakpoints,

inspect variabl es, and evaluat e expressions. Using the int egrated debugger enables you t o f i nd and f i x bugs in t he debugger

wi t hout having to l eave the IDE.

The debugger i n t he Samsung Mobile Widget SDK runs a Chromi um version of WebKit . This WebKit emul ator is always used f

debugging in t he IDE, no matt er w hat t arget device(s) are specif ied in your proj ect .

This document assumes that t he reader has some experi ence wit h debugging and wit h Eclip se. For an intr oducti on to t he

subject, see Debugging wi t h t he Ecl ipse Plat f orm. For detailed information about debugging in Eclipse, visit http://hel

eclipse.org/helios/index.jsp and fo l low t he l inks given in Java development user guide > Concepts > Debugge

7.0 - Start ing the Debugger

You should be able run your code befor e you st art t he debugger. When you are ready to start debugging, set a breakpoint in

your code by double-cl icking the m arker bar a long the lef t side of t he editor w indow:

You can clear a breakpoint by double-clicking the blue breakpoint icon.

To st art debugging, ri ght-cl ick t he target device in t he Device List and choose Debug As > Widget , o r c l ick the Debug icon

the toolbar:

Your debugging session w ill begin as soon as t he breakpoint is encount ered i n your code. If no br eakpoint s are set, or no

except ions occur, t he debugging session is indist inguishable fr om running wi t hout debugging. It may be necessary t o work w

your widget in the emulator until the f irst breakpoint is reached. When this happens, the IDE may display a Confirm
http://www.ibm.com/developerworks/library/os-ecbug/http://help.eclipse.org/helios/index.jsphttp://help.eclipse.org/helios/index.jsphttp://help.eclipse.org/helios/index.jsphttp://help.eclipse.org/helios/index.jsphttp://www.ibm.com/developerworks/library/os-ecbug/


35/69

Perspective Swit ch dialog box, tell ing you that you are about to open the Debug perspective:

Click Yes t o open the Debug perspective. You may wi sh to check t he Remember my decision checkbox t o suppress t hi

conf i rmat ion in the fu t u re .

If t he dialog box shown below appears when you start a debugging session, you must cl ose all running emul ator s and t hen

restart t he debugging session. If you have previewed an Opera widget , you m ust close the Opera browser, t oo.

7.1 - The Debug Perspective

The default configuration of the Debug perspective looks like this:

This layout is probably familiar to experienced programmers. The default configuration of the Debug perspective does not

include some feat ures that you may f ind useful - the Expressions t ab, f or instance. When you set up t he Debug perspect ive

way you l ike i t , you may want to use the Window > Save Perspective As... comm and to save it . When you have saved your

favori te conf igurat ion, i t is avai lable in t he Open Perspective dia log box, ident i f ied w it h whatever name you gave i t :


36/69

You can open the Debug perspect ive manuall y, w henever you like. Eit her choose Window > Open Perspective or c l ick the

Open Perspective icon on the toolbar:

The Debug perspect ive incl udes some vi ews and actions that do not apply t o JavaScript debugging.

7.1.1 - The Stack View

When you select a stack f rame in t he Stack view, the current l ine of execut i on in t he selected f rame is h ighl ighted in t he

edit i ng window. In the fo l lowing example, the execut ion of HelloWorld has been suspended at t he 14th li ne of t he main

js f i le :

You can navigate f rom one source f i le t o another in t he edit ing window by cl icking the appropriate stack f rames.

The St ack view shows a thr ead as eit her Runningor Suspended. When t he program i s suspended, t he St ack view shows the

thread context and al lows you to interact wit h the stack i tself . Each l ine in t he Stack view gives the f unct ion, f i le , and l ine

number, whenever possible.

Any except ion t hat occurs is d isplayed in the Stack view, wit h t he cause of t he except i on and t he current l ine.

7.1.2 - The Debug ToolbarThe Debug Toolbar provi des a convenient way t o invoke common debugging comm ands. It is incorporated i nto t he St ack vie

These comm ands are also available i n t he Run menu.


37/69

These icons correspond to t he fol lowi ng commands:

I c o n Co m m a n d De s c r i p t i o n

Remove

Terminated

Launches

Clears terminated debug targets from the Stack view.

Resume Resumes a suspended widget application.

Suspend Suspends the process so that you can browse or modify code, step through execution, and

so on.

Terminate Terminates the debug target.

Disconnect Disconnects the debugger from the debug target.

Step Into Steps into the highlighted statement.

Step Over Steps over the highlighted statement.

Step Return Steps out of the current method. Execution stops after exiting the method.

Use Step Filters Turns step filters off and on. When on, all the step commands apply step filters.

7.1.3 - The Edit View

The Edit view enables you to look at and edit your code whil e you are debugging. This view also provides several real- t im e

sources of debugging inform ati on.


38/69

When you hover over an element in your code, a hover window appears, d isplaying the current value of the e lem ent. In the

fo l low ing screenshot, the hover window report s that the current value of the statevariable is hello_again:

Th e Inspect menu i t em in the Edit v iew's r ight-cl ick "context" m enu provides a powerfu l w ay to examine your code. To use

select an expression in your code, r ight- click i nside t he Edit view, and choose the Inspect menu i tem:


39/69

A window appears showing how that expression is evaluated by the runtime. For example, in the following screenshot, the

wi ndow shows the DOM values for t he hel loElemvariable:

The scrol lbars here demonstr ate t hat a great deal of in f ormat i on is avai lable in t h is window.


40/69

7.1.4 - Variables, Breakpoint s, and Expressions

The default configurat ion of t he Debug perspect ive includes a Variables view and a Breakpoint s view. You may f i nd it usefu

add the Expressions view t o thi s part of t he perspective:

The Variables view displays information about the current stack frame. When you select a variable in the Variables view, th

detai ls pane at t he bot t om of the view displays i t s contents:

You can use t he Variables view's search f uncti on t o sim plif y t he t ask of f i nding variables. Changing values in t he Variables v

is not current ly supported.

To watch a variable persistently, right-click the variable name and choose Watch. The Expressions view appears, l ist ing t he

variable you have selected. You can also choose t o display t he Expressions view by choosing Window > Show View >

Expressions.

When you select an it em in t he Expressions view, it is evaluat ed and the result i s displayed in the det ails pane on the ri ght of the view.

You can manually add an expression in t his view by cli cking the Add new expression l ine. If you enter an invalid expression,

value is report ed as "".

The Breakpoint s view d isplays t he breakpoint s you have set in your code and helps you manage t hem. In the f ollow ing

screenshot, t he detail s pane has been expanded for clari t y.


41/69

You can set breakpoint s in JavaScript f i les and inside t he JavaScript sect ions of HTML fil es. Line br eakpoint s are set on an

executable l ine in a program; i f you at t empt to set a breakpoint on a cur ly brace or other non-executable l i ne, t he breakpo

appears on the next executabl e line. Breakpoints are persistent fr om one debugging session t o the next and are saved when

you quit Ecli pse.

Breakpoints can be set i n HTML files, but must be set on lines that cont ain JavaScript . In t he foll owing example, a breakpoi

can be set only on li ne 9.

8

9 10 Gallery

Set t ing condit i onal breakpoint s can impr ove your control over t he debugging session. In t he foll owing screenshot, a condit i o

has been set t hat causes t he breakpoint t o suspend execut ion only w hen the statevariable is hello. Condit i ons must be

specif ied in valid JavaScript; if the JavaScript is invalid, execution stops whenever the breakpoint is reached. Note that the

is an ast erisk in t he Breakpoints t ab here; t his condit i onal breakpoint has not yet been saved. You should be sure to save

condit ional br eakpoint s before using t hem i n your debugging session.

You can use t he Hit Count sett ing to cause either the thread or the target to suspend when the breakpoint has been hit

t i mes. Af ter the h it count has been reached, t he breakpoint is d isabled unt i l i t is reenabled or i t s hi t count is changed.


42/69

The t oolbar in t he Breakpoints view pr ovides access to comm on breakpoint -handling t asks for Eclipse users. Some of t hese

icons may not have been impl ement ed in t his release of t he Samsung Mobile Widget IDE - for example, t he "Skip All

Breakpoints" comm and does not cur rent ly w ork. In addit ion, some of t hese tool s do not apply t o debugging JavaScript for

widgets.

The icons listed in the following table may be useful while you are working with your breakpoints in a JavaScript widget

pro ject :

I c o n Co m m a n d De s c r i p t i o n

Remove

Selected

Breakpoints

Removes any of the breakpoints you have selected.

Remove All

Breakpoints

Removes all of the breakpoints from the Breakpoints view.

Go to File Opens the file for the breakpoint in the editing window, highlighting the breakpoint location.

For m ore inform at ion about w orking wit h breakpoints in Ecl ipse, vis i t http://help.eclipse.org/helios/index

jsp and open Java development user guide > Refer ence > Views > Breakpoint s View .

7.1.5 - Debug Configurations

A debug configurat ion enables you t o give a unique name to a debugging configurat ion and to associate t he named

conf igurat ion w it h a part icular device. The Common tab in the Debug Configurations dialog box enables you to conf igure

aspect s of your debugging environment , such as it s Unicode encoding and st andard input and output .

To create a debug configurati on, select Run > Debug Configurations.

Debug configurati ons are sim ilar t o run configurat ions. For infor mat ion about sett ing up and using run configurat ions, see

Previewing on a Browser.

7.2 - Other Debugging Opt ions

I f you are having problem s wi t h your JavaScript code that appear only on an ext ernal brow ser - or if for any reason you pref

not t o use t he debugger in t he IDE - you can choose among good debuggers in the i nter nal WebKit emul ator, Firefox, and

Opera. If you pay careful attention to interoperability and cross-browser issues when creating your widget, your JavaScript

problem s can usuall y be solved by any debugger.

In browsers wit h debuggers, you can br owse the DOM, examine source code, and set breakpoint s as needed. You can also us

the browser's reload mechanism (for pages or widgets) to start over whenever you like. However, you must edit your widget

t he Samsung Mobile Widget SDK, not i n the debugger. Aft er edit ing, re-r un the w idget f rom t he SDK to relaunch t he browse

wi t h all your changes and overrides included.

7.2.1 - Debugging using Web Inspector

Any WebKit -based brow ser, includi ng the WebKit emul ator used by t he Samsung Mobile Widget SDK to support Dolf in br ows

has an internal debugger called the Web Inspect or. You can use this to debug your Dolf in widget by right-clicking an elemen

the widget while it is being emulated (not while it is being debugged in the IDE) and selecting Inspect Element . The Inspec
http://help.eclipse.org/helios/index.jsphttp://help.eclipse.org/helios/index.jsphttp://-/?-http://-/?-http://help.eclipse.org/helios/index.jsphttp://help.eclipse.org/helios/index.jsp


43/69

Element menu i t em launches Web Inspector .

Th e Web Inspector is not act ive w hen t he IDE's debugger i s act ive. To swi t ch fr om t he t he IDE's debugger t o t he Web

Inspector, choose Disconnect in the Stack view menu, and then right click and choose Inspect Element .

7.2.2 - Debugging using Opera

Samsung's Windows Mobile devices use the Opera browser to display widgets. Therefore, the Samsung Mobile Widget SDK

launches Opera aut omat icall y whenever you double-cl ick a Windows Mobile devi ce in Device List (or choose Run As >

Widget ). Debugging on Opera can be a good way of uncovering problem s that mi ght occur on t hose devices.

Samsung's Windows Mobile devices use the Opera browser to display widgets. The Samsung Mobile Widget SDK launches Ope

autom ati cally w henever you preview a widget on a Windows Mobil e device. To debug using Opera, choose Run As > Widget

then, after Opera launches, select Tools > Advanced > Developer Tools in Opera. A new work area appears at the bottom

t he screen, l abeled "Loading Dragonfly. " Dragonfly i s the name of Opera's debugger. When Dragonfly has f ini shed loading,

debugging w indows appear.

7.2.3 - Debugging wit h Firefox and Firebug

The Firebug debugger is an add-on f or Mozilla's Firefox br owser. You might choose t o use Firebug if i t is already your pref er

debugging environment . You can learn mor e about Firebug and download it here: h t t p : / / ge t f i r ebug.com/

Firefox does not all ow you t o use XMLHttpRequest f rom a local f i l e . For a workaround, see XMLHt t pRequest Issues.

http://getfirebug.com/http://-/?-http://-/?-http://getfirebug.com/


44/69



Widget-Development Tips

This part of t he Samsung Mobile Widget Development Guidediscusses advanced topics for wi dget devel opment .

8.0 - Widget SDK User Interface Tips

This section introduces several ideas for using the Samsung Mobile Widget SDK in ways you may not have discovered on your

own.

8.0.1 - Viewing the Error Log

You can add an Error Log view t o the Instance Management views at t he bott om of t he IDE wi ndow. You can use t he Error L

t o t rack probl ems as you work w it h t he Samsung Mobile Widget SDK. To add thi s view:

1. Select Window > Show View

2. Choose Other to d isplay the Show View dialog box

3. Expand t he General node and select Error Log f rom t he l ist

4. Cl ick t he OK but ton

8.0.2 - Viewing Widget Library API

You can look at the implementations of the Widget Library (TouchWiz) API whenever you like, by expanding the JavaScri

Resources node in the Project Explorer view and then expanding the Widget Library node:

Both the comments in this code and the implementation details can help you develop your widgets. Many of these API elem

work i n d if f erent w ays on dif ferent p lat f orms; you should implement cross-browser strategies in your code to accommodate

these dif ferences. For inf ormat ion, see Best Pract ices f or Wid get Development and Samsung Mobil e Widget Specif icat ion V
http://-/?-http://c%7C/depot/development/tools/widget/plugins/com.uievolution.widget.help/assets/pdf/Samsung_Mobile_Widget_Specification_V0.93.pdfhttp://c%7C/depot/development/tools/widget/plugins/com.uievolution.widget.help/assets/pdf/Samsung_Mobile_Widget_Specification_V0.93.pdfhttp://-/?-


45/69

8.0.3 - Using Open With Web Page Editor

When you right-click an HTML f i le in Project Explorer view, you can choose Open With > Web Page Editor and work w i t h th

f i l e in an int erest i ng way. The Source Editor view opens wit h t wo wi ndows: t he top w indow shows a preview of the HTML

output and the bot t om wi ndow shows the edit able source code:

There are tabs along the bottom of this view. In the preceding screen shot we are looking at the Design tab. For a bet t er

preview of the HTML f i l e you can cl ick the Preview tab.

The mouse cursor in the preceding screen shot is near a small left arrow that you can click to reveal a palette of visual item

you can drag into t he editor. For example, i n the fo l l owing i l lustr at ion, t he Line Break i t em has been dragged fr om t he HTM

4.0 menu and dropped bet ween "Hello" and "World":


46/69

8.1 - Browsers

Widget developers must be aware of the browsers that are installed on their target devices and the browsers that are used

the emulator in the IDE.

8.1.1 - Browsers on TouchWiz Devices

The most popular br owsers on current TouchWiz devices are:

NetFront (ACCESS), for some Samsung Handset Platf orm (SHP) dev ices

Opera, for Window s Mobile devi ces

Dolf in (WebKit ), for some SHP devices

The emulat or displayed by t he IDE uses Netf ront , Opera, or WebKit , dependi ng on the device you have chosen t o test.

Debugging your w idget in t he IDE alw ays uses the WebKit em ulat or.

Most users of t he Samsung Mobile Widget SDK att empt t o develop w idgets t hat w il l r each as many TouchWiz devices as

possible. The most successful wid gets will run on any platf orm and on any browser. Building widget s like t his requires caref

at t ent ion t o interoperabi l i t y issues, as out l ined in Best Pract ices f or Wi dget Development.

8.1.2 - Previewing on a BrowserSomet imes you might pr efer t o preview your wid get on a web browser instead of in t he IDE's device emul ator . To do thi s, yo

must set up a new run conf igurat ionfo r your w idget p ro j ect .

First , select t he name of t he project in Proj ect Explorer t hat you would l ike t o run in a browser. Then select t he small t r ian

next t o the Run icon and choose the Run Configurations... i t em.

Open the Widget node in the Run Configurations dialog box that appears and select one of t he Proj ect - DeviceNameentr

Give this new run configuration a descriptive name. The Project and Device entry f ie lds are f i l l ed in wit h values taken

from the project that was selected when you opened this dialog box. Select "Web Browser" in the Run with section. The

dialog box should look somet hing like t his:
http://-/?-http://-/?-


47/69

Cl ick t he Web Browser Pref erences l ink t o choose the w eb browser on which you would l ike t o test your widget:

Ensure t hat t he "Use ext ernal Web br owser" radio but t on is select ed, as shown above.

To add a new browser t o th is l ist , c l ick t he New... button and navigate to the browser's location on your hard drive.

When you have set up t he run configurat ion and are ready to run your w idget on an exter nal brow ser, choose Run > Run

Configurations... and cl ick the Run but ton a t the bo t tom o f the Run Confi gurations dialog box.


48/69

Browsers handle security with XMLHttpRequest in d i f ferent ways. For example, t he Dolf in br owser

used by many Samsung devices allows XMLHttpRequest access to remote sites, but other browsers

may not. For more inf ormat ion, see Working with Mult ip le Browser Plat forms.

8.2 - Import ing an Exist ing Widget

You may somet im es need to br ing an existing wid get int o the Samsung Mobile Widget SDK. Follow t his procedure to im port

successfully:

1. Choose File > Import

2. Expand t he Samsung node and choose Widget. Cl ick the Next but ton .

3. Cl ick t he Browse butt on and navigate t o the d irect ory contain ing the .WGT f i le you want t o impor t .

4. Select t he desired .WGT f i l e and cl ick the Open but ton .

5. Cl ick t he Finish but ton .

6. Drag a device into t he Device List f or the new proj ect .

The foll owing screen shot shows a list of availabl e widget f i les that coul d be displayed when a user cli cks t he Browse but to

When you impor t an exist ing wi dget, t he Samsung Mobile Widget SDK reads the wi dget's config.xml f i l e and t ransfers th

values to the new project's generic project.xml f i l e . Dif f erent versions of a w idget 's config.xml f i l e are required for

different platforms. When you package (export) a project, the Samsung Mobile Widget SDK generates the correct form of

config.xml, based on t he project 's project.xml f i l e and the plat f orm of t he target device. For inform at ion about

packaging a project , see Packaging a Wi dget.

Note for earlier widgets developed using the Opera Widget Emulator:

Widgets wri t ten t o work wit h the Opera Widget Emulator may have the fo l l owing l ine of code in the head of index.htm

al low t hem work wi th t he Opera Widget Emulat or:

if(parent.emulator)parent.emulator.begin(window);

You should rem ove this line f rom your index.html f i le. The Samsung Mobil e Widget SDK aut omat icall y work s wit h t he Op
http://-/?-http://-/?-


49/69

Widget Emulat or. Cal l ing emulator.begin again overw rit es t he Samsung Mobile Wi dget API widget obj ect, causing

incorrect emulat ion behavior for setScroll and resizeWindow.

8.3 - Best Pract ices for Widget Development

You can use these "best p ract ices" t o reduce development t im e and avoid fr ust rat ions. Follow ing these t ips ensures that you

use of t he Samsung Mobil e Widget SDK is eff icient and that your wi dgets will run on mult iple pl atf orms.

1. Test your widget in mult iple brow sers. See Working with Mult ip le Browsers, be low, fo r more in fo rmat ion .

2. Use overri des, not dif fer ent proj ect s, t o support m ult iple screen resolut ions and brow sers. For an example of handling

wi ndow resizing in your code, see Window Resizi ng, be low.

3. Handle diff erences caused by mul t iple screen resolut ions in your CSS fi les, rat her t han by hard-codi ng the sizes in

JavaScript or HTML.

4. Be careful about dif fer ences in how brow sers handle events. See Event Handli ng, be low, fo r more in fo rmat ion .

5. There are a number of cross-plat for m issues wit h the XMLHttpRequest DOM API, i ncluding security restri ct ions and t

possibil ity of a null response. For more information, see XMLHtt pRequest Issues, be low.

For technical details about some of the requirements of cross-platform design, see the Samsung Mobile Widget Specif icat io

V0.93.

8.3.1 - Working with Multiple Browser Platforms

New m obile devices use m any dif fer ent web brow sers. Samsung devices might use NetFront (ACCESS), Opera, or Dolf in

(WebKit ) , and more browsers are l ike ly to be supported soon. I t is important to t est your widget on t he browsers for a l l of y

target devices.

JavaScript engines vary fr om brow ser t o browser and somet im es fr om version to version wit hin a single brow ser. Thi s means

you many not be able to use some browser objects and their corresponding event handlers to develop your widget, dependi

on the t arget browser and i t s JavaScript implem entat i on.

You can run your widget in t he emulat or or in any browser you have set up i n the Run Confi gurations dialog box (seePrevi ewi ng on a Browser). In addit ion, you can package your widget and run it in Opera.

To package your widget, right-click a device in your Device List and ch oose Package f rom the context menu (or use th

CONTROL+SHIFT+P key combination). You can f ind a complete description of packaging widgets in Packaging a Wi dget.

To preview your widget, double-cl ick the .WGT f i le or drag the f i le into an Opera window. Please note that Opera caches th

wi dget, so you will need to cl ose both t he widget and Opera when maki ng changes.

8.3.2 - Window Resizing

A comm on cross-brow ser i ssue is w indow resizing. SHP devices support t he resizeWindow API, but Windows Mobile d evicmay support only t he resizeTo API. You can solve t his problem w it h a try/catch constr uct ion l i ke t h is:

try {

widget.window.resizeWindow(width,height);

} catch(e) {

window.resizeTo(width,height);

}

You should use overri des t o support devices that have dif fer ent screen sizes. For mor e inf ormat ion, see Overr ides.
http://-/?-http://-/?-http://-/?-http://c%7C/depot/development/tools/widget/plugins/com.uievolution.widget.help/assets/pdf/Samsung_Mobile_Widget_Specification_V0.93.pdfhttp://c%7C/depot/development/tools/widget/plugins/com.uievolution.widget.help/assets/pdf/Samsung_Mobile_Widget_Specification_V0.93.pdfhttp://-/?-http://-/?-http://-/?-http://-/?-http://c%7C/depot/development/tools/widget/plugins/com.uievolution.widget.help/assets/pdf/Samsung_Mobile_Widget_Specification_V0.93.pdfhttp://c%7C/depot/development/tools/widget/plugins/com.uievolution.widget.help/assets/pdf/Samsung_Mobile_Widget_Specification_V0.93.pdfhttp://-/?-http://-/?-http://-/?-


50/69

8.3.3 - Event Handling

This is a good idi om t o use in event handlers:

function doSomething(e) {

if (!e) {

var e = window.event;

// e gives access to the event in all browsers

}}

I f you use t h is id iom wit h in l ine event handl ing, you must pass the event to the handler manual ly.

Rest rict event handl ing t o t he W3C DOM Level 2 Event specif icat ion: ht t p: / / www .w 3.org/ TR/ 2000/ REC-DOM-Level-2-Events

20001113/

For addit ional inf orm ati on, use resources such as h t t p : / / www.qu i r ksmode .org/ j s / in t roevents.h tm l and ht t p :/ / w w w.

quirksmode.org/ j s/ events_access.ht ml .

8.3.4 - XMLHt tpRequest Issues

Various brow sers have diff erent securit y restrict ions when using XMLHttpRequest f rom a local f i le .

IE - a l lowed w it h warning dia log

Safari - al lowed

Opera - disallow ed - test as widget instead

Firefox - d isal lowed - add t he fo l lowi ng ( temporar i ly) t o your code. This wi l l present a d ia log box when t he request is

made:

try {

netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead");

} catch (e) {

// There should be no errors. This try/catch construction should allow

// you to run this code in any browser.

}

Th e responseXML f rom a XMLHttpRequest can be nul l i f the r equest header has not been in i t ia l ized correct ly. The

results can vary on different browsers. To correctly get the desired response, set the content header before making the

request. For example:

request.setRequestHeader("Content-type", "text/xml");

Th e XMLHttpRequest API is not cur rent ly supported by Int ernet Explorer . Your code should creat e a cross-brow ser

XMLHttpRequest object by creat ing a new ActiveXObject, w hen necessary, as in the f ollow ing sample f rom t he RSS

Reader template's network.js f i le :
http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/http://www.quirksmode.org/js/introevents.htmlhttp://www.quirksmode.org/js/events_access.htmlhttp://www.quirksmode.org/js/events_access.htmlhttp://www.quirksmode.org/js/events_access.htmlhttp://www.quirksmode.org/js/events_access.htmlhttp://www.quirksmode.org/js/introevents.htmlhttp://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/


51/69

function getXMLHttpRequest() {

var xmlHttp = null;

try {

xmlHttp = new XMLHttpRequest();

}

catch (e) {

try {

xmlHttp = new ActiveXObject("Microsoft.XMLHTTP");

}

catch (e) {}

}

return xmlHttp;

}

8.3.5 - Opera Debugging

Developers who are target ing the Opera browser oft en use calls to t he opera.postError funct ion as a debugging t echnique.

should not leave t hose calls in your code when r unning your widget on a device. Call s t o opera.postError wil l produce an

exception. Protect any debugging calls by surrounding them with try/catch statements.

8.4 - Using a Proxy Server

To successful ly w ork w it h t he Samsung Mobile Widget SDK when your development environm ent uses a proxy server t o conn

to the Internet, you will need configure Eclipse to recognize your proxy. To do this, follow these steps:

Go to Window > Preferences, open the General node, and choose t he Network Connections node.

Select Manual in the Act ive Provider drop-down l ist at t he top of the Network Connections dialog box.

You wi ll need t o specif y your pr oxy server for both t he HTTP and HTTPS schemas. Select HTTP and click t he Edit but ton

The dialog box should look somet hing like t his:


52/69

You wi l l specify your pr oxy server by enter ing inform at ion in t h is form:

http://proxy_server_name: port_number

For example, t he Edit Proxy Entr y dialog box in the following screen shot has been f i l led in with a typical host name and p

The port number is t runcated here by the size of t he entry f i e ld.

When you cl ick t he OK but t on in thi s dialog box, your new pr oxy server appears on the Network Connections page for t he

HTTP schem a. Repeat t he pr ocess for HTTPS.

There are several br owser-specif ic det ails you should be aware of :

Opera: You must restart the Opera browser for your proxy set t ings to take ef f ect .

NetFront : The NetFront br owser requires that t he sett ings for HTTP and HTTPS be ident ical. In addit i on, if t he proxy se

is local t o your machine, t he NetFront br owser does not w ork i f you specify t hat your host is localhost; in t his case,

127.0.0.1 instead.


53/69

8.5 - Samsung Widget API

The Samsung Widget API are used only f or t he Samsung mobil e plat for m. They do not w ork in a w eb brow ser.

The following list gives the API that are available to widget developers and a brief description of each API element. For mo

details, see the Samsung Mobil e Widget API Ref er ence, on t he Samsung Mobile Innovat or w eb site.

widget.openURL(address); Opens t he specif ied page.

widget.preferenceForKey(key); Retur ns t he value associat ed wit h the specif ied key.

widget.setPreferenceForKey(value, key); Saves a value wit h a specif ied key in t he mobil e device. The value is retai

even i f a device is turned of f .

widget.sysInfo.getLanguage(); Returns the language code for the language currently configured for the device.

widget.sysInfo.network.getIsNetworkAvailable(); Determines whether a mobi

samsung mobile widget development guide 1-3-1

Documents