Mobile Widgets SDK manual

This part aims to describe the Mobile Widget SDK Plug-in. This plug-in, once integrated in the Eclipse platform, provides tools for Mobile Widgets creation, compilation, export and emulation.

The following points will be detailed:

• Creation of a Mobile Widget,
• Project Preferences,
• Running a Mobile Widget,
• Exporting a Mobile Widget.

Before you install the plug-in, make sure that your development environment fits the following requirements:

• Java 1.5 or higher is installed. It must be a Java Development Kit (JDK).
  See Java runtime installation part to download it.
• Eclipse 3.5 or higher is used.
  See Eclipse installation part to download it.
• Optional: Perl 5.12.2 or higher (used for documentation generation only).
  The latest stable version can be downloaded on: http://www.perl.com/download.csp.

From eclipse folder, launch " eclipse.exe " file to open Eclipse.
There are four ways to create a new Mobile Widget Project: from the Toolbar, the New Widget Project menu or the New Project... menu.

Launch " New Mobile Widget " from the Toolbar

Click on the " New Mobile Widget " button on the Toolbar (marked in blue).

Launch " New Mobile Widget " from the New Widget Project menu

In top menu bar, 2 possibilities:

• select " File " then " New " then " Widget Project ".

• using (" Alt + Shift + N ") shortcut and select " Widget Project ".

Launch " New Project " from the Toolbar

Click on the " New " button on the Toolbar (marked in blue).

Launch " New Project " from the New Project... menu

In top menu bar, 2 possibilities:

• select " File " then " New " then " Project... ".

• using (" Alt + Shift + N ") shortcut and select " Project ".

" New Project - Select a wizard " dialog box is opened.
Select " Widget Project " under " Mobile Widgets SDK " folder.
Select " Next > " button to continue.

The New Mobile Widget Wizard

" New Mobile Widget Project - Create a new Mobile Widget Project " dialog box is opened.

Widget Type

The Widget Type is defined here. As indicated on the wizard page, there is two choises:

• " Tiny Mobile Widgets " are generic widgets which can be deployed on the whole range of handsets, in both widget and standalone modes.
• " Mobile Widgets " are also available in both widget and standalone modes. They allow backward compatibility and have less memory constraints than " Tiny Mobile Widgets ". As a result, they do not support low end handsets.

Widget Configuration

First of all, the global parameters fields have to be filled in. Here is a short description of these parameters:

• " Project name " (mandatory): The name of the project, as it will appear in the workspace.
• " Widget name " (mandatory): The name of the new created Mobile Widget.
  It must begin with an upper-case alphabetic character.
  It can contain any alphabetic or digit character.
• " Widget version " (mandatory): The version number of the Mobile Widget.
  Default value displayed is: 1.0.0.
• " Widget description " (optional): a short description of the widget.
• " Widget category "(mandatory): the widget category is selected in a list.
  8 categories are purposed : "Fun & Game", "News & Feeds", "Communication", "Audio & Pics & Video", "Business", "Maps & Travel", "Shopping", "Tools & Utilities" and "Misc".

VRML Model usage

" New Mobile Widget Project - Choose VRML Model " dialog box is opened.

The new Widget Project is built from an existing VRML model.
These models are functional and provide sample code.
The VRML model to use is selected on the second page of the wizard.
A short description and a screenshot of the selected item are displayed on the right.
When a model is selected, the Widget project creation is completed.
You can click on the " Finish " button.

A complete Widget Project is created.
It is fully functional and can be run once created by using Run As > Mobile Widget.
Its sources can be used as a starting point for another application or just to provide code samples.

Project structure

A newly created project has the following structure:

• The " doc " folder contains a screenshot of the widget.
• The " exports " folder contains the files generated for different export configurations.
  Each export has its own subfolder.
• The " i18n " folder contains languages files.
• The " images " folder contains the project's images.
• The " lib " folder is a symbolic link bound to the selected widget type and containing subfolders.
  (images, protos, tests, ...).
  It must not be modified (only by advanced users).
• The " src " folder contains the project sources.
  All the project's source files must be saved in this folder.
• The " tmp " folder contains data generated during compilation.

Depending on the selected widget type, the project icon in the Eclipse workspace is different:

• orange if it is a " Mobile Widget ".
• cyan if it is a " Tiny Mobile Widget ".

Global preferences

In top menu, select " Window " then " Preferences ".

" Preferences " dialog box is opened.
Select " Mobile Widgets ".
You can configure :

• the Perl path,
• the signing of Applets,
• the signing of MIDlets,
• the properties for BlackBerry packaging.

In order to generate the widgets documentation, you must provide the path where Perl is installed.
Specify the path in the " Perl bin directory: " textfield.
By default, this textfield is completed by C:\Perl\bin.

In order to sign Applets and MIDlets, you must provide a keystore and other data, as an alias, a storepass and a keypass.
If the checkbox is checked and correct data are entered in the different textfields, the Applets and/or the MIDlets will automatically be signed when created.

In order to package Widgets for BlackBerry phones, some properties must be set. The version is mandatory and must be selected in a list.

Project preferences (Properties)

The project preferences page allows modifying the Widget version and the Widget style after the project creation.

2 possibilities:

• by right click on the Widget Mobile Project then select " Properties " then " Widget preferences ".

• using (" Alt + Enter ") shortcut. " Widget Preferences " is already selected.

" Properties for MobileWidget - Widget preferences " dialog box is opened.
The " version " and the " SDK " of the selected project are displayed.
They can be modified and taken in account by the project.
WARNING: Only advanced users should modify the SDK.

There are three different ways to run the Mobile Widget.

• If you are used to the Eclipse environment, you can run the widget in a standard way from the Run Configurations dialog box.
• If you are new to Eclipse, you can configure and launch the widget from the Toolbar.
• For a quick launch with default configuration, you can use the Run As menu.

" Run Configurations " for running the Mobile Widget

In top menu bar, select " Run " then " Run Configurations... ".

" Run Configurations - Create, manage, and run configurations " dialog box is opened.
In the configurations list, choose " Mobile Widget Application " then " New_configuration ".
You can specify a name for this configuration, in the " Name " textfield.
By default, it will be named " New_configuration ".
Select a project on which the configuration will be applied by clicking on the " Browse... " button.

In the " Task " group, select " Compile and test ".

The " Emulator " group is enabled.
There are three configurations items:

• " Wipe data ": check this box to clean the RMS entries on the emulator.
• " Current Language ": by clicking the " Select language " button, you can choose one of the available languages in the project (from the i18n folder).
• " Current Resolution ": choose a graphical resolution by clicking the " Select size " button.

" Supported language " or " Supported size " dialog boxes are opened after " Select language " or " Select size " button selected.

" Run Configurations - Create, manage, and run configurations " dialog box is completed.
Click on the " Apply " button to save your configuration.
Then click on the " Run " button to launch it.
The WRL sources are compiled for the current language and resolution and the emulator is launched.

Important:
If you are running a " Tiny Mobile Widget ", the " Project " group of the " Run Configurations " page will look like this:



If you have modified the " Widget Entry Point ", you must update this value for the project to compile.

Note:
In a " Tiny Mobile Widget Project ", the entry point can not be named " main.wrl ".
Whereas in a " Mobile Widget Project ", the entry point must always be named " main.wrl ".

" Toolbar " for running the Mobile Widget

Select a Widget Project in " Project Explorer ".

Click on the " Configuration for tests and export " button on the Toolbar (marked in blue).

" Widget configuration - Parameters for test with emulator and export " dialog box is opened.

The Widget Version can be modified in the " Version " group.

The " Test with Emulator " group is enabled.
There are three configurations items:

• " Wipe data ": check this box to clean the RMS entries on the emulator.
• " Current Language ": by clicking the " Select language " button, you can choose one of the available languages in the project (from the i18n folder).
• " Current Resolution ": choose a graphical resolution by clicking the " Select size " button.

" Supported language " or " Supported size " dialog boxes are opened after " Select language " or " Select size " button selected.

Once the setup is done, click on the " Finish " button to save it.

Important:
If you are configuring a " Tiny Mobile Widget ", the " Compile " group is added in the " Widget Configuration " page will look like this:



If you have modified the " Widget Entry Point ", you must update this value for the project to compile.

Note:
In a " Tiny Mobile Widget Project ", the entry point can not be named " main.wrl ".
Whereas in a " Mobile Widget Project ", the entry point must always be named " main.wrl ".

This configuration will be used when:

• the " Run Mobile Widget Application " button of the Toolbar (marked in blue) is clicked.

• using (" Alt + Shift + X " then " W ") shortcut.

" Shortcut " for running the Mobile Widget

For convenience, a launch shortcut is provided.

To access it, right click on a " Mobile Widget " or a " Tiny Mobile Project " or one of its elements.
Then for running, 2 possibilities :

• select " Run As " and " Mobile Widget ".

• using (" Alt + Shift + X " then " W ") shortcut.

This shortcut provides the following configuration:

• It wipes the RMS data and runs the widget on the emulator.
• The default language and the default resolution are the ones selected in the Toolbar configuration screen.

There are three different ways to exporting the Mobile Widget:

• If you are used to the Eclipse environment, you can export the widget from the " Run Configurations " dialog box.
• If you are new to Eclipse, you can export the widget from the Toolbar.
• For quick single exports, you can use the context menu.

" Run Configurations " for exporting Mobile Widget

In top menu bar, select " Run " then " Run Configurations... ".

" Run Configurations - Create, manage, and run configurations " dialog box is opened.
In the configurations list, choose " Mobile Widget Application " then " New_configuration ".
You can specify a name for this configuration, in the " Name " textfield.
By default, it will be named " New_configuration ".
Select a project on which the configuration will be applied by clicking on the " Browse... " button.

In the " Task " group, select " Export Widget ".

The " Package " group is enabled.
Select one or several packages to create.
There are seven " Packages " purposed:

• " Package Applet ": generate " JAR " files (in the " exports/applet " folder) and launch the applet in browser.
• " Package for AppShop ": create " JAR " and " JAD " files (in " exports/midlet " folder) that can be uploaded on Orange AppShop.
• " Package for Android Marketplace ": create a package for Android (in " exports/android " folder) that can be uploaded on Android Marketplace and on Orange AppShop.
• " Package for Orange Widgets ": create a package (in " exports/mmp " folder) for Orange Widgets.
• " Package for RIM AppWorld (BlackBerry) ": create a package for BlackBerry (in " exports/blackberry " folder) that can be uploaded on RIM App World and on Orange AppShop.
• " Package for Ulight " (available only for Tiny Mobile Widgets): create a package (in " exports/ulight " folder) for Ulight.

Click on the " Apply " button to save your configuration.
Then click on the " Run " button to launch the export task(s).

" Toolbar " for exporting Mobile Widget

Select a Widget Project in " Project Explorer ".

Click on the " Configuration for tests and export " button on the Toolbar (marked in blue).

" Widget configuration - Parameters for test with emulator and export " dialog box is opened.
In the " Export " group, you can choose the packages to generate when the export task is launched.

Important:



The " Package for Ulight " option is only available for " Tiny Mobile Widgets ".

Click on the " Finish " button to save the configuration.

Once the setup is done, click on the " Export Widget " button on the Toolbar (marked in blue) to launch the selected export tasks.

" Context Menu " for exporting Mobile Widget

Select a Widget Project in " Project Explorer ".

To access to Context Menu, right click on a " Mobile Widget " or a " Tiny Mobile Project " or one of its elements.
Then select " Mobile Widgets SDK Tools " and select one of " Package ".
It allows launching export tasks one by one.

The " Package for Ulight " option is only available for " Tiny Mobile Widgets ".
The " Export widget " option launches the packages tasks selected in the " Toolbar configuration " screen.

Note: in case of a RIM AppWorld (BlackBerry) package, some properties need to be configured. See the part about Global preferences for more info.

Documentation in HTML can be generated from the comments present in the VRML code of the widget.

There are two different ways to generate documentation the Mobile Widget:

• If you are used to the Eclipse environment, you can generate documentation from the " Run Configurations " dialog box.
• For quick, you can use the context menu.

" Run Configurations " for generating documentation

In top menu bar, select " Run " then " Run Configurations... ".

" Run Configurations - Create, manage, and run configurations " dialog box is opened.
In the configurations list, choose " Mobile Widget Application " then " New_configuration ".
You can specify a name for this configuration, in the " Name " textfield.
By default, it will be named " New_configuration ".
Select a project on which the configuration will be applied by clicking on the " Browse... " button.

In the " Task " group, select " Generate Documentation ".
Click on the " Run " button.
The documentation is generated in the " doc " folder of the Mobile Widget project and opened in a web browser.

" Context Menu " for generating documentation

Select a Mobile Widget Project in " Project Explorer ".

To access to Context Menu, right click on a " Mobile Widget " or a " Tiny Mobile Project " or one of its elements.
Then select " Mobile Widgets SDK Tools " and select " Generate documentation ".

The documentation is generated in the " doc " folder of the Mobile Widget project and opened in a web browser.

Add project nature

A project obtained from repository check-out which contains all the mandatory elements may not have the required " Mobile Widget " nature.
In this case, the options of the context menus, the " Run Configurations " and the Toolbar are not available for the project.
To convert such a project in a " Mobile Widget " or a " Tiny Mobile Widget " project, use the " Mobile Widgets SDK Tools ":

To access to Context Menu, right click on another element not a " Mobile Widget " and not a " Tiny Mobile Project ".
Then select " Mobile Widgets SDK Tools ".
Then select your between " convert to Tiny Mobile Project (Generic) " or " convert to Mobile Widget Project ".

Once the project converted, the related actions become available and the needed symbolic links are created.
The project nature is indicated by the icon for " Mobile Widget Project " or for " Tiny Mobile Widget Project ".

Remove project nature

If you convert a project that should not have been, the nature can always be removed by using the context menu.

To access to Context Menu, right click on a " Mobile Widget " or a " Tiny Mobile Project ".
Then select " Mobile Widgets SDK Tools ".
Then select your between " Remove Mobile Widget Nature ".

The project nature is indicated without an icon.

The Micro Emulator configuration file is available here:

• Windows OS: " C:\Documents and Settings\{user name}\.microemulator\config2.xml "
• Linux OS: " /home/{user name}/.microemulator/config2.xml "

Add these two lines in your " Micro Emulator " configuration file (" config2.xml ") in " <system-properties> " paragraph:

<system-property VALUE="{your proxy host}" NAME="http.proxyHost"/> <system-property VALUE="{your proxy name}" NAME="http.proxyPort"/>