Opera Platform™ SDK

1. Introduction

Opera Platform™ is an SDK and a Web Application Framework that is built on top of the Opera Browser with the Opera Platform™, and facilitates creating locally or remotely hosted web applications on devices. These devices are typically mobile phones, but the Opera Platform™ Application Framework is not limited to running on any particular platform or operating system.

This documentation covers the Opera Platform™ SDK, also refered to as the Opera Platform™ Application Framework and how you can use this to create these web applications.

1.1. Before you start

An author that wants to author Opera Platform™ Web Applications needs to be familiar with the following technologies and specifications:

• XML
• HTML/XHTML
• CSS
• ECMAScript/javascript
• DOM levels 0-3
• AJAX technologies
• Web Applications 1.0
• The Opera Platform™ DOM Interface specification

1.2. Opera

At the heart of the Opera Platform™ Application Framework lies the Opera web browser. The browser provides all the neccessary means to create an application by providing a web browser with support for web standards: HTML, CSS, javascript

1.3. Opera Platform™ DOM Interface

The Opera Platform™ DOM Interface provides a javascript interface for accessing and interacting with the device's native capabilities. This interface is covered in detail in the Opera Platform™ DOM Interface specification.

1.4. Opera Platform™ Application Framework

The Opera Platform™ Application Framework provides the developer with a set of base functionality that enables the user to write Client-Side Web Applications, known as Opera Platform™ Web Applications.

1.5. Opera Platform™ Web Applications

Opera Platform™ Web Applications are an application that uses the Opera Platform™ Application Framework, and the underlying functionality offered by the framework and the application player.

2. Getting Started

2.1. What is included in the Opera Platform™ SDK

The Opera Platform™ SDK is a framework and a tool set for creating web based application for mobile devices. The Opera Platform™ SDK consists of the base framework, documentation, some example web applications and tools for packaging and deploying projects.

The Opera Platform™ SDK contains everything a developer needs to create web based applications for mobile devices.

2.2. Installing Opera Platform™

Opera Platform™ is provided as an installable archive for Windows Smartphone 2003 and Symbian Series60. The installation process consists of transferring the archive to the device, and installing it on the device.

These instructions provide a step by step guide on how to install Opera Platform™ on the device on the supported devices.

2.2.1. Windows Smartphone 2003

1. Download Opera Platform™ and Opera home plug-in cab files
2. Connect the device to ActiveSync
3. Open ActiveSync and click Explore
4. Go to My Smartphone
5. Navigate to \Storage\windows\Start Menu\Accessories.
6. Copy the two cab files to this directory.
7. Terminate all running instances of Opera by clicking Start Menu → System Management → Task Manager".
8. Click on Start and then Accessories in the Start Menu.
9. You should now see the files that you cut and paste into the Accessories folder, click on the Opera Platform™ cab file to start the installation of the browser.
10. Do the same with the "homescreen plug-in" cab file. Click on it to install.
11. This will install Opera and Opera Platform™ to \Storage\Application Data\Opera\, and make an entry for it in the Windows Smartphone application menu.

2.2.2. Symbian Series60

1. Use Bluetooth, or any other suitable connection, to transfer the Opera Platform™ SIS to the device.
2. Open the received message on the device and choose install. Choose to install the application on the memory card.
3. The installer will create an Opera Platform™ application launcher on the Symbian Series60 application menu.
4. Open the application menu and click on the Opera Platform™ icon to start Opera Platform™.

2.3. Installing Opera Platform™

A deployable Opera Platform™ project consists of a install package which installs in the correct folder, defined by Opera Platform™. The package has to be transferred and opened on the device.

2.3.1. Symbian Series60

The install procedure is the same as when installing Opera Platform™. Transfer the Opera Platform™ package to the device and open it. The package has to be installed on the same drive as Opera Platform™. For best performance it is recommended to install both on the memory card.

An alternative install procedure is to copy the Opera Platform™ content directly to the Opera Platform™ folder on the device. It is possible to use a PC memory writer to access the device memory directly from the PC. It is also possible to get direct access to the device by using P3NFS, a tool which only is available for Linux, this is described in the "Recommended Tools" section. An alternative method is to use Nokia PC Suite to copy the content to the device, and then use a file explorer on the device to copy it to the correct location. The content of the Opera Platform™ project should be placed so that the home.html is located in the folder "E:\System\Opera\OP\".

2.3.2. Windows Smartphone 2003

There is two ways of installing the Opera Platform™ content on the device. Either use a cab installer or copying the content of the Opera Platform™ project directly.

The install instructions for installing a cab file with Opera Platform™ content is the same as when installing Opera Platform™. The cab installer will automatically install the content in the correct location.

Microsoft ActiveSync gives direct access to the device memory and it is possible to copy the content directly from a computer to the device. The advantage of this compared to using a cab installer, is that it is quicker and the possibility of transferring only parts of the project.

The default location of the Opera Platform™ content on the device is '\Storage\Application Data\Opera\Oxygen'. Open ActiveSync and choose 'Explore', go to 'My Smartphone' and locate the directory. Copy the Opera Platform™ content into this folder, so that the home.html is located in the Oxygen directory.

2.4. Required Tools

The tools required for developing and installing Opera Platform™ is software for transferring data to the device, a text editor for developing and a connection method to the device.

It is possible to connect to the devices with Bluetooth, IR or USB connection. Most Smartphone devices come shipped with a USB cable, which is the fastest method of connection. Symbian Series60 phones seldom come with the required cable, and Bluetooth is the preferred transfer method.

Microsoft ActiveSync is required to transferring files to Windows Smartphone 2003 devices. ActiveSync is downloadable and available from the Microsoft web site. The software is not available for other Operating Systems.

2.5. Recommended Tools

A convenient way of developing on a Symbian Series60 device is by using P3NFS on from a Linux system. P3NFS is a server and client which makes it possible to connect the device hard drive directly to the local file system. This makes it possible to develop directly on the device, without having to transfer the content for each change. P3NFS is not available for any other operating systems than Linux.

Nokia PC Suite is a tool which makes it possible to connect the device to the local file system on a Microsoft Windows machine. Nokia PC Suite does not give directly access to the whole device, but it is usable for transferring to the device and then copy it from the device to the defined Opera Platform™ location.

There are several Symbian Series60 tools available for helping the development of Opera Platform™ applications. FExplorer is an advanced file explorer which gives access to the whole file system on the device. This can be used to copy the required files to the Opera Platform™ folder. Another useful application is "Memmon" which is a memory monitor tool for Symbian. The tool makes it possible to monitor the memory usage of the application, and can be used to detect memory issues with the applications.

When developing Opera Platform™ Applications on desktop with the Opera Browser, there are several tools which helps with development. The DOMConsole is an web extension to Opera which gives a detailed representation of the DOM tree. These tools are available here.

3. Deploying your first Opera Platform™ Project

A finished Opera Platform™ project consist of a directory which contains Opera Platform™ and the Opera Platform™ Application Framework. Each application has an own directory that is included in registeredServices.xml.

The file home.html in the top level directory defines the starting point of the framework. The content has to be installed on the device, and on start up, the Opera browser will look for this file in a specified location.

Deploying an Opera Platform™ project is a task of packaging the Opera Platform™ Application Framework and Application files into a installable package, that easily can be distributed and installed on the different phone models.

The different phone operating systems has their own install package format, but both has approximately the same functionality. The two formats which are supported by the Opera Platform™ SDK is the Windows Smartphone 2003 "CAB" format, and the Symbian Series60 "SIS" format.

There are free tools available which makes installable packages for both SIS and CAB, but some of these have compatibility issues. The Opera Platform™ SDK provides scripts to assist with creating install packages.

3.1. Packaging Your Application

3.1.1. Symbian Series60 SIS

Creating a SIS file is a process of first creating a package file which describes the archive and where to put the files, and then run this through Makesis. Makesis will read the package file and create a SIS archive from the specified files.

The sisgen tool which is available in the Opera Platform™ SDK does this process automatically. Launch the tool from the command line with the sis output file as the first argument, and the path to the Opera Platform™ project as the second argument.

Please note that sisgen uses a developer Symbian Unique Number developer, which only should be used for development, and not for distribution. A product specific Unique Number can be obtained from the Symbian web pages.

Windows:

 c:\perl sisgen.pl --help
 c:\perl sisgen.pl platform.sis platform\

Linux:

 $ ./sisgen.pl --help
 $ ./sisgen.pl platform.sis platform/

The tool will then create the package file for the specified directory. The files will be installed in the directory on the device which Opera is set to look for them. The package file and the directory will then be runned through the MAKESIS program, which will create the SIS file.

3.1.2. Microsoft Smartphone 2003 CAB

The CAB format is a Microsoft archiving format, and the Smartphone CAB installers consist of all the files packed in this format together with a setup.xml file that describes the install process. This structure and the setup.xml file is created automatically by Cabwiz, but to create installers for Opera Platform™ this process has to be done manually.

The cabgen tool is a part of Opera Platform™ SDK and does this process automatically. It creates the setup.xml file and puts all the files in the Opera Platform™ project into the required form. It then creates an input file to the traditional CAB archive tool Makecab, which again creates the CAB Installer. This tool use the Microsoft MAKECAB utility, which is only available for Windows.

Windows:

    c:\perl cabgen.pl --help

    c:\perl cabgen.pl -f platform.cab c:\Platform 
  

The CabGen tool will create a CAB Installer which installs the Opera Platform™ content files into the correct folder on the device.

3.2. Deploying Your Service

When the archive with Opera Platform™ Framework and the wanted Opera Platform™ Application is created, the deployment process consists of installing the archives on the device.

The procedure of installing Opera Platform™ and the required applications is described in the "Installing Opera Platform™" and "Installing Opera Platform™" section.

4. Building your first application

We will here walk through how to make a simple application with Opera Platform™. To start with, we will construct the application as a simple web application, independent of Opera Platform™. Then we will make it a full-flegded Opera Platform™ application.

The example application displays a "Fortune Cookie". This is just a short saying or proverb. The application will retrieve the fortune cookie from a web server and update the screen. It will also support updating the cookie when the user clicks a button.

4.1. Creating the HTML document

An Opera Platform™ application is started when an application HTML page is loaded. The application HTML document is no different from other HTML documents, with a few exceptions. We will get to those later. For now, we create a tiny skeleton html file like this:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Fortune cookie</title>
    <script type="text/javascript">
    var FortuneApplication = function() {
      // do nothing.
    }
    </script>
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>

When opened in the browser, the "Hello world!" header is displayed. The javascript function/class is also loaded, but does nothing.

4.2. Styling your application

Once you have created an application document, you are free to style it using all regular web techniques. CSS rules can be added in separate documents, or directly in the application document.

The new version of our application document now has a stylesheet attached, and we have added some html tags that we will later manipulate using javascript:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Fortune cookie</title>
    <link 
      rel='stylesheet' type='text/css'
      media='handheld, screen, projection'
      href='FortuneCookie.css' />
    <script type="text/javascript">
      var FortuneApplication = function() {
        // do nothing.
      }
    </script>
  </head>
  <body>
    <h1>Fortune Cookie</h1>
    <p id="cookie" class="cookiecontainer">
      Fortune cookie appears here.
    </p>
    <p><button>Fetch</button></p>
  </body>
</html>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Fortune cookie</title>
    <!-- Add a handheld stylesheet
    <link 
      rel='stylesheet' type='text/css'
      media='handheld, screen, projection'
      href='FortuneCookie.css' />
    <script type="text/javascript">
      // A helper class that fetches a fortune from a web server. 
      // It notifies objects that have registered as listeners 
      // whenever it is updated.
      var FortuneFetcher = function(url) {
        this.url = url;  // url of fortunes
        this.conn = null;
        this.fortune = null;
        this.listeners = [];
              
        // Callback function used for xmlhttprequest.
        this.HttpCallback = function() {
          if (this.readyState==4) {
            if (this.status==200 || this.status==304) {
              this.fortuneFetcher.parseFortune(this.responseXML);
              this.fortuneFetcher.notifyListeners();
            } else {
              // If an error occurs here, we silently ignore it.
            }
          }
        }

        // Send a http request to retrieve a new fortune cookie
        this.update = function() {
          this.conn = new XMLHttpRequest();
          // save this, as "this" refers to the XMLHttpRequest
          // object when the callback is called
          this.conn.fortuneFetcher = this; 
          this.conn.onreadystatechange = this.HttpCallback ;
          
          /** The following line is a hack. It appends a random integer
           *  to the request as a GET parameter. This fools the webserver
           *  and browser into always returning a new fortune. Without it
           *  we could be getting cached data.
           */
          var fullUrl = this.url + "?" + Math.floor(Math.random()*100000);
          this.conn.open('GET', fullUrl, true);
          this.conn.send(null);
        }

        // Parse the xml returned from the http request.
        this.parseFortune = function(xml) {
          var e = xml.getElementsByTagName('fortune')[0];
          if (e) {
            // get the text of the fortune. Normally, this might grab 
            // more than just the data of the first childnode, but 
            // this will do for the example.
            this.fortune = e.childNodes[0].nodeValue;
          } else {
            this.fortune = "not able to load fortune!";
          }
        }

        // Adds a callback function that is called whenever a new 
        // fortune is received.
        this.addEventListener = function(func) {
          this.listeners.push(func);
        }

        // Calls all the registered callback functions, with the new 
        // fortune as the parameter.
        this.notifyListeners = function() {
          for (var n=0, func; func=this.listeners[n]; n++) {
            func(this.fortune);
          }
        }
      }

function displayFortune(f) {
  var container = document.getElementById('fortune');
  // delete everything in the fortune paragraph
  while (container.removeChild(container.childNodes[0] )) {}
  container.appendChild(document.createTextNode(f));
}

document.onload=function () {
  fetcher = new FortuneFetcher("http://oxine.opera.com/fortune.php");
  fetcher.addEventListener(displayFortune);
  fetcher.update();
  var e = document.getElementById('updatebutton');
  e.addEventListener('click', function() {fetcher.update()} , false );
}

</script>
  </head>
  <body>
    <h1>Fortune Cookie</h1>
    <p id="fortune" class="cookiecontainer">
      Fortune cookie appears here.
    </p>
    <p><button id="updatebutton">Fetch</button></p>
  </body>
</html>

<?xml version="1.0"?>
<serviceDefinition>
  <name>Hello world</name>
  <guid>hw0123456789</guid>
  <version>0.1</version>
  <screenName>Hello!</screenName>
  <author>Opera Software ASA</author>
  <javascriptNS>Fortunes</javascriptNS>
  <icon>serviceIcon.png</icon>
  <menupriority>123</menupriority>
</serviceDefinition>

<url serviceid='729' shortname='Fortunes' >Fortunes/index.html</url>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>
      Fortune cookie
    </title>
    <link rel='stylesheet' type='text/css' media='handheld, screen, projection' href='FortuneCookie.css' />
    <link rel='stylesheet' type='text/css' media='screen,handheld,projection' href='../chrome/persistentStyles/persistentStyles.css' />
    <!-- Add the Opera Platform™ Core -->
    <script type="text/javascript" src="../oxygen.js"></script>
    <script type="text/javascript">    
      /**
       * Main application class. supports displaying and refreshing fortunes.
       */
      var Fortunes = function() {

        this.fetcher = null;
        
        /**
         * Handle all incoming messages.
         *
         */         
        this.onMessageReceived = function(message) {        
          // If the message contains an Init member.
          if (message.containsMembers('Init') ) {
            this.fetcher = new FortuneFetcher("http://oxine.opera.com/fortune.php");
            this.fetcher.addEventListener(this.displayFortune);    
            var e = document.getElementById('updatebutton');
            e.app=this;
            e.addEventListener('click', function() {this.app.refreshFortune() }, false );
            this.refreshFortune();
          }
        }

        /**
         * Inserts the fortune cookie into the DOM.
         */        
        this.displayFortune = function(fortune) {
          var container = document.getElementById('fortune');
          while (container.removeChild(container.childNodes[0] )) {} // delete everything in the fortune paragraph
          container.appendChild(document.createTextNode(fortune));        
        }
        
        /**
         * Refresh fortune cookie
         */
        this.refreshFortune = function() {
          this.fetcher.update();
        }
       
      }

      /**
       * A helper class that fetches a fortune from a web server. It notifies
       * objects that have registered as listeners whenever it is updated.
       *
       */
      var FortuneFetcher = function(url) {
        this.url = url;  // url of fortunes
        this.conn = null;
        this.fortune = null;
        this.listeners = [];
              
        /**
         * Callback function used for xmlhttprequest.
         *
         */
        this.HttpCallback = function() {
          if (this.readyState==4) {
            if (this.status==200 || this.status==304) {
              this.fortuneFetcher.parseFortune(this.responseXML);
              this.fortuneFetcher.notifyListeners();
            } else {
              // If an error occurs here, we silently ignore it.
            }
          }          
        }
              
        /** 
         * Send a http request to retrieve a new fortune cookie
         */
        this.update = function() {
          this.conn = new XMLHttpRequest();
          this.conn.fortuneFetcher = this; // save this, since "this" is wrong when the callback is called.
          this.conn.onreadystatechange = this.HttpCallback ;
          
          this.conn.open('GET', this.url, true);
          this.conn.send(null);
        }

        /**
         * Parse the xml returned from the http request.
         */
        this.parseFortune = function(xml) {
          var e = xml.getElementsByTagName('fortune')[0];
          if (e) {
            // get the text of the fortune. Normally, this might grab more then
            // just the data of the first childnode, but this will do for the
            // example.
            this.fortune = e.childNodes[0].nodeValue
          } else {
            this.fortune = "not able to load fortune!";
          }          
        }

        /**
         * Adds a callback function that is called whenever a new fortune
         * is received.
         */
        this.addEventListener = function(func) {
          this.listeners.push(func);
        }

        /**
         * Calls all the registered callback functions, with the new 
         * fortune as the parameter.
         */
        this.notifyListeners = function() {
          for (var n=0, func; func=this.listeners[n]; n++) {
            func(this.fortune);
          }
        }      
      }


</script>

  </head>
  <body>
    <h1>
Fortune Cookie
    </h1>
<p id="fortune" class="cookiecontainer">
This is where the fortune cookie will appear.
</p>
<hr>
<p>
<button id="updatebutton">Fetch</button>
</p>
  </body>
</html>

5. Opera Platform™ applications

The applications in the Opera Platform™ SDK come in two different flavors: System applications and regular applications.

5.1. System applications

System applications are applications that provide housekeeping or low-level helper functionality that can be used by regular Opera Platform™ applications. These are typically loaded permanently into memory.

5.2. Applications

Applications live in separate global objects, in javascript terminology known as window objects. These applications can reside locally, or in different domains.

These applications can set up event listeners for broadcast messages, as specified by the Web Applications 1.0 specification. Additionally, these applications can create and send messages, thereby providing a loose coupling between the framework and other applications. Typically the applications reside in directories on the devices filesystem, and consist of XHTML, CSS, javascript, images, configuration and other resources. The application is described in the application description file.

5.3. CSS Styling rules

Styling Opera Platform™ applications is an optional feature of the Opera Platform™ SDK. The application developer can either leave the responsibility to the Opera Platform™ Application Framework, or the developer can make all styling in the application. A combination of the two methods can also be chosen. By linking to the stylesheet chrome/persistentStyles/persistentStyles.css a number of very basic styles are predeclared.

In addition to normal CSS styling rules, authors should be aware of Opera's Extensible Rendering Architecture, ERA. Descriptions of how these rendering modes work are covered in two articles; MyOpera developer community: Making Small Devices Look Great and Opera's rendering modes.

In the Opera Platform™ Application Framework, the topmost window is rendered in SSR-mode, while any applications are running inside an IFRAME, and are thus rendered in regular screen rendering mode.

5.4. Icons, themes and branding

When an Opera Platform™ SDK application is run, styling rules from the chosen user theme will be automatically applied to the service. The location of the default theme is determined in the file core/textStringsMainDocument. Example:

var o2_startupsetting_o2_theme='./themes/baseTheme/style.css';

Default application icons are stored in the chrome/icons folder, and are PNG images with the dimension 64×80 pixels that hold multiple images. The location of the icon for an application is determined by the icon element of a appdef.xml file.

1. The application grid active image: 40×42 pixels. This icon is placed in the top left corner of the icon file.
2. The application grid inactive image: 40×42 pixels. This icon is placed in the bottomleft corner of the icon file.
3. The list view active image. 16×17 pixels. This icon is placed in the top right corner of the icon file.
4. The list view inactive image16×17 pixels This icon is placed in the bottom right corner of the icon file.

A sample template for Adobe Photoshop containing a sample icon is available. This template file contains preset guidelines that assists in creating icons.

5.5. Application loading and unloading

Normally, the Opera Platform™ Application Framework will dynamically load and unload applications as needed, and will only keep one regular application in memory at one given time. If needed, this behavior can be changed, and an application can be made persistent in memory by adding type="persistentApp" to registeredapps.xml. Be aware that keeping applications persistent in memory should be done only after careful considerations, because devices typically have limited memory capabilities.

5.6. Memory

Profiling javascript's memory usage is very difficult to do in a desktop browser. Browsers generally don't guarantee that they release any used memory to the operating system. As such, it is highly recommended to do the actual memory profiling on real target devices. On devices we need to observe the available memory using a tool. In addition, the Opera Platform™ DOM Interface provides two methods for checking memory usage on the device from javascript:

interface System {
  ...
  readonly attribute unsigned long long totalMemory;
  readonly attribute unsigned long long freeMemory;
};

5.7. CPU

Observing the CPU usage of an application on the desktop usually does not provide information directly transferable to mobile devices. The CPU usage of an application on the desktop might be negligible, while it has a significant impact on a mobile device.

While there may not always be good direct methods to measure CPU usage, this is most easily observed with visual debugging: Applications will feel unresponsive and slow once CPU usage is higher than desired.

5.8. Network access

The Opera Platform™ DOM Interface provides the neccessary means to check the availability of networks such as GPRS, GSM and similar. The getInterfaceStatus(interfaceName) call returns a short in the form of a bit mask. Exact information about this bitmask is provided in the Opera Platform™ DOM Interface specification.

In addition to checking individual networks, one can attach event listeners to the interfaceChanged event on the device object.

interface InterfaceEvent : Event {
  readonly attribute DOMString          interface;
  readonly attribute unsigned short     status;
  void initInterfaceEvent(in DOMString typeArg, 
                          in boolean canBubbleArg, 
                          in boolean cancelableArg, 
                          in DOMString interfaceArg, 
                          in unsigned short statusArg);

  // For DOM Level 3 support
  void initInterfaceEventNS(in DOMString namespaceURI,
                            in DOMString typeArg, 
                            in boolean canBubbleArg, 
                            in boolean cancelableArg, 
                            in DOMString interfaceArg, 
                            in unsigned short statusArg);
}

5.8.1. Internet Connection Strategy: Series 60

When Opera Platform™ connects to the Internet, the following strategy is used:

1. First, try the APN with highest priority
2. If this is not successful, Opera Platform™ asks the user
3. If connecting with the APN given in 2) is successful, this APN will be used, if still present.
4. If the previous APN is not present, the user will be asked again

If only one APN is defined, the user will never be asked, and similarily, if the APN with the highest priority works, the user will never be asked.

If the underlying operating system returns an error message, the user will be asked for another access point.

Should the user have set up or selected an APN where external access is not available, for instance an MMS APN, the application developer can initiate an APN reset, by making a call to the opera.resetAPN() method. After this method has been called, Opera should again ask which access point to use when a network connection is required.

Note that this strategy only applies to Symbian/Series 60 devices, as Windows Smartphone devices have a different connection strategy where the wanted AP is specified outside of the application.

5.9. Menus

Menus in Opera Platform™ Applications are most easily created using the built-in Menu API. Creating a menu is done in the Init event of an application:

5.9.1. Creating menus

this.createMenu();

If a developer wants to create a menu with predefined menu contents, the path to and name of the menu file is included as an argument:

this.createMenu('menufile.xml');

When the menu has been created, a global menu object named o2_menu is available, and you can control the menu's behavior and content by calling the relevant methods for the menu.

5.9.2. Menus and IDs

When a menu has been created, an initial menu with the id main is automatically created, and it can be queried and acted upon using regular dot notation.

5.9.3. Adding menu items

To add new items to a menu, the method addChild() is called on the menu in question. Adding a menu item to the root menu is done this way:

o2_menu.main.addChild(String label, String ID, new O2_Command(function))

label is the menu label. ID is the id of the menu item, that can be used for later processing.

The O2_Command is a new instance of a command that should be associated with the menu. An example call to create a menu entry can thus look like this:

o2_menu.main.addChild("Test item","test_item_1",
                       new O2_Command(function(){alert('Test item clicked')} )

5.9.4. Adding and changing actions

If a menu has been created from an XML file, it might not have any action associated with it. In that case, the action for a named menu entry can be changed/added using the o2_menu.setActionOnItem() method:

o2_menu.setActionOnItem(new O2_Command(function), String ID)

5.9.5. Getting a named menu item

To get a handle to a menu entry, the getItem() method is used:

o2_menu.getItem(String ID)

ID is a reference to the ID of the menu item for which the handle is wanted.

5.9.6. Disabling a menu entry

A menu entry can be disabled using the disable() method on a menu item:

o2_menu.getItem(String ID).disable()

5.9.7. Removing a menu entry

A menu entry can be removed using the removeChild() method on a menu item:

o2_menu.getItem(String ID).removeChild(String ID);

5.9.8. Dynamic menus

A developer can have different menus, for instance for different views:addMenu() method:

o2_Menu.addMenu(String MenuID)

MenuID is the ID for the given menu. This can later be addressed by regular dot-notation:

o2_menu.addMenu('test_menu');
o2_menu.test_menu.addChild("test item","test_item", 
                           new O2_Command(function(){alert('test')});

Switching to the new menu is done by making a call to the o2_menu.setActiveMenu() method:

o2_menu.addMenu('view_2'); // create a new menu
o2_menu.view_2.addChild("test item","test_item", 
                           new O2_Command(function(){alert('test')});
o2_menu.setActiveMenu('view_2); // The active menu will now be 'view_2'

5.9.9. Submenus

Adding submenus is achieved by adding child menus to a given menu entry using regular dot notation, referencing the id of the menu entry you want to add child entries to:

o2_menu.main.addChild('Open sub','entry_1',
                      new O2_Command(function(){alert('test')});
// The following code will create a submenu item as a child of 
// 'entry_1'
o2_menu.main.entry_1.addChild(('Submenu item','entry_2',
                      new O2_Command(function(){alert('Submenu')});

5.10. Dialogs

Dialogs, such as warning and information dialogs in the Opera Platform™ Application Framework are created using the built-in dialog API. There is a dialog demo application included with the Opera Platform™ SDK that can be examined.

Creating a dialog is done by making a call to this.createDialogController(). This will create the dialog as a singleton, making it available to the developer in the o2_dialogs object

The default dialog type is an informational dialog.

this.createDialogController()

After the dialog singleton has been created, a dialog is added by calling the o2_dialogs.addDialog() method.

5.10.1. Info dialogs

A simple information dialog can be created this way:

var infoDialog=o2_dialogs.addDialog('test_info');
infoDialog.type='info';
infoDialog.text='Some text';

This will create an info dialog with the label Some text.

5.10.2. Warning dialogs

Warning dialogs behave exactly like informational dialogs, except they use different default styling.

var infoDialog=o2_dialogs.addDialog('test_warning');
infoDialog.type='warning';
infoDialog.text='A warning';

5.10.3. Error dialogs

Error dialogs behave exactly like info and informational dialogs, except they use different default styling.

var infoDialog=o2_dialogs.addDialog('test_error');
infoDialog.type='error';
infoDialog.text='An error has occured';

5.10.4. Question dialogs

A slightly more complex dialog, is the question dialog. This dialog provides two options, for instance Yes and No, or OK and Cancel. The following example will create a dialog named test_question with the question Are you really sure?, with the options Yes and No:

o2_dialogs.addDialog(
  'test_question', 
  'Are you really sure?', 
  'question', 
  'Yes', 
  'No', 
  new O2_Command(function(){alert('false')}), 
  new O2_Command(function(){alert('true')})
);

5.10.5. Input dialogs

The input dialogs automatically creates text input fields when created. When the dialog is closed, any input values are available in an array named o2_dialogs.inputValues. The labels for the text inputs are given as the last argument to the addDialog method:

 2_dialogs.addDialog(
  'test_inputs', 
  'First and last name, please', 
  'input', 
  'Ok test', 
  'Cancel Test', 
  new O2_Command(function(){alert('false')}), 
  new O2_Command(function(){alert(o2_dialogs.inputValues.join('\n\n'))}),
  ['your first name:', 'your second name:']
);

5.10.6. Showing dialogs

To display a dialog, a call is made to the dialog's show() method. The example below shows how to display the dialog from the previous example:

o2_dialogs.test_inputs.show()

5.11. Setting navigation bar labels

To set default values for the navigation bar labels, a developer can call the o2_menu.setPriority1Text and o2_menu.setPriority2Text:

o2_menu.setPriority1Text( text );
o2_menu.setPriority2Text ( text );

If the developer omits to set the navigation bar text, these texts default to Options and Back respectively. The default texts can be overridden in the file library/textStringsMenu.js

If the menu is set to close with the same keyboard shortcut as it is opened, the text for this label can be set using o2_menu.setCancelText():

o2_menu.setCancelText(String text)

5.11.1. Menu button strategy

An application developer can choose to close the menu with the same key it is opened with by calling o2_menu.closeWithOpenButton(true):

o2_menu.closeWithOpenButton(boolean)

If this is set to false (default), the menu will have a separate cancel button.

5.12. The Navigation Bar

The contents of the navigation bar in Opera Platform™ can be set dynamically by passing messages using utilities.sendInfoToNavigationbar():

utilities.sendInfoToNavigationBar( navbarDestination, content );

The navbarElement is one of four:

• priority1Text: The textual content of the Priority 1 softkey. On Series 60 devices, this is equivalent to the left softkey, while this is the right softkey text on Smartphone devices
• priority2Text: The textual content of the Priority 2 softkey. On Series 60 devices, this is equivalent to the right softkey, while it is unavailable on Smartphone devices (The key is reserved for the system Start menu).
• infoCenterText: The textual content of the information field between the two softkey texts.
• infoCenterImage: A CSS classname for the info center image
• classNameNavigationbar A CSS class name for the navigation bar.

The utilities.sendInfoToNavigationbar accepts setting multiple values at once. The following example will set both softkey texts by passing one message:

utilties.sendInfoToNavigationBar( "priority1Text", "Example 1", "priority2Text","Example 2" )

5.13. The History Stack

In the Opera Platform™ Application Framework, the purpose of the history stack is to create a stack of functions that are called when you go back in history, so an application developer can control in which state an application is put when the user presses the "Back" key.

Adding something to the history stack is done by making a call to the method addToHistoryStack( <Function> function, <mixed> arguments ) where function is a function reference, and arguments is a variable number of arguments that will be passed to the function when it is called. Calling the function at the top of the history stack is done by making a call to callLastFromHistoryStack(). Note, this will not remove the function from the stack.

When the back button is pressed, the following happens:

1. The topmost element on the history stack is removed
2. The new topmost element on the stack is executed.

5.13.1. Explicitly removing elements from the history stack

If a developer needs to explicitly remove the topmost element on the stack, this is done by calling the method popHistoryStack().

5.14. Localizing the Opera Platform™ Application Framework

Certain parts of the Opera Platform™ Application Framework can be localized by editing the appropriate localization documents. These documents are all javascript files containing a number of variable declarations.

5.14.1. Softkey menus

The localizable strings in the application-level softkey menus is localized by editing the file /core/textStringsMainDocument. Below are the default contents of this file.

/* ServiceManager */
// All occurences of 0xa0 are used to prevent reflow problems
var O2_Text_ServiceManager_LoadingService='Loading Service ...';
/* Adapter */
/* WMSmartphone2003 */
var O2_Text_Adapter_WMSmartphone2003Profile_CommandPriority1Frontpage='Menu';
var O2_Text_Adapter_WMSmartphone2003Profile_CommandPriority2Frontpage='Start';
var O2_Text_Adapter_WMSmartphone2003Profile_CommandPriority1RegularService=String.fromCharCode(0xa0); 
var O2_Text_Adapter_WMSmartphone2003Profile_CommandPriority2RegularService='Start';
/* Desktop */
var O2_Text_Adapter_DesktopProfile_CommandPriority1Frontpage='Menu';
var O2_Text_Adapter_DesktopProfile_CommandPriority2Frontpage='Camera';
var O2_Text_Adapter_DesktopProfile_CommandPriority1RegularService=String.fromCharCode(0xa0);
var O2_Text_Adapter_DesktopProfile_CommandPriority2RegularService='Back';
/* Series 60 */
var O2_Text_Adapter_Serie60Profile_CommandPriority1Frontpage='Menu';
var O2_Text_Adapter_Serie60Profile_CommandPriority2Frontpage='Camera';
var O2_Text_Adapter_Serie60Profile_CommandPriority1RegularService=String.fromCharCode(0xa0);
var O2_Text_Adapter_Serie60Profile_CommandPriority2RegularService='Back';

5.14.2. The application grid

The localizable strings in the application grid are localized by editing the file /AppGridNew/textStringsAppGrid.js. Below are the default contents of this file.

var O2_Text_AppGrid_Menu_MoveToFolder='Move to folder';
var O2_Text_AppGrid_Menu_MoveToFolderRootName='Root';
var O2_Text_AppGrid_Menu_NoMenuItemIsSelected='No menu item is selected';
var O2_Text_AppGrid_Menu_NameForNewFolder='The name of the new folder:';
var O2_Text_AppGrid_Menu_NoMenuEntryIsSelected='No menu entry is selected';
var O2_Text_AppGrid_Menu_ViewTypeGrid3='Grid 3';
var O2_Text_AppGrid_Menu_ViewTypeGrid4='Grid 4';
var O2_Text_AppGrid_Menu_ViewTypeList='List';
var O2_Text_AppGrid_Menu_ApplicationCanNotBeDeleted='This application can not be deleted';
var O2_Text_AppGrid_Menu_DefaultPriority1Text='Options';
var O2_Text_AppGrid_Menu_DefaultPriority2Text='Back';
var O2_Text_AppGrid_Menu_InteractionPriority1Text='Ok';
var O2_Text_AppGrid_Menu_InteractionPriority2Text='Cancel';
var O2_Text_AppGrid_Menu_ThisWillDeleteAllSettings='This will delete all your settings';

5.14.3. URL Manager

The localizable strings in the URL manager are localized by editing the file /URLManager/textStringsURLManager.js. Below are the default contents of this file.

var O2_Text_URLManager_Menu_NewBookmarkName='Name of the bookmark:';
var O2_Text_URLManager_Menu_NewBookmarkURL='Address for the new bookmark:';
var O2_Text_URLManager_Menu_NewBookmarkInfo='(http://www. will be added automatically if protocol is missing)';
var O2_Text_URLManager_Menu_NoBMSelected='No bookmark selected';
var O2_Text_URLManager_Menu_DefaultPriority1Text='Options';
var O2_Text_URLManager_Menu_DefaultPriority2Text='Back';
var O2_Text_URLManager_Menu_InteractionPriority1Text='Ok';
var O2_Text_URLManager_Menu_InteractionPriority2Text='Cancel';

5.14.4. Menu strings

The localizable strings in the application menus are localized by editing the file /library/textStringsMenu.js. Below are the default contents of this file.

// menus
var O2_Text_MenuClass_defaultPriority1Text='Options';
var O2_Text_MenuClass_defaultPriority2Text='Back';
var O2_Text_MenuClass_cancelText='Cancel';
var O2_Text_MenuClass_openText='Select';
var O2_Text_MenuClass_interactionPriority1Text='Ok';
var O2_Text_MenuClass_interactionPriority2Text='Cancel';

// dialog
var O2_Text_DialogClass_defaultPriority1Text='Options';
var O2_Text_DialogClass_defaultPriority2Text='Back';
var O2_Text_DialogClass_cancelText='Cancel';
var O2_Text_DialogClass_openText='Ok';

class O2_OutboundMessage {
  void addMember(<string> memberName, <mixed> data)
  void addReceivers(<number> argument1, argument2, ...)
  void send()
}

class O2_InboundMessage {
  <boolean> object containsMembers(<string> argument1, argument2, ...)
  <mixed> object getMember(<string> memberName)
  number getSenderId()
}

class O2_UserServicePrototype {
  <O2_OutboundMessage> object createMessage()
  void sendMessage(<string> memberName, <mixed> data=null, <int> receiver='')
  void goToFullScreen()
  void leaveFullscreen()
  void addToHistoryStack(<function> function, <mixed> parameter 1, ...<mixed> parameter n)
  void callLastFromHistoryStack()
  void createMenu(<string> url='')
  void createDialogController(<string> url='')
  "abstract" void onBack()
  "abstract" void onBack()
  "abstract" void onBlur()
  "abstract" void onMessageReceived(<O2_InboundMessage>)
  "abstract" void onFocus()
  "abstract"; void onKeypress(<string> keyName)
  void popHistoryStack()
   void sendDebugInfo(string, priority)
};

O2_callAfterInstantiation=function(){

/* A constructor function to extend the compiled application*/} 

<?xml version="1.0" encoding="UTF-8"?>
<guidList>
  <item>
    <screenName>Log</screenName>
    <guid>103</guid>
    <launchName>MissedCallHandler</launchName>
    <icon>../theme1/img/appgridIcon4.png</icon>
    <menupriority>-1</menupriority>
  </item>
</guidList>
    

<?xml version="1.0" encoding="UTF-8"?>
<menus>
  <menu name='main'>
    <entry value='ref_1'>first entry</entry>
    <entry value='submenu_1'>a submenu</entry>
    <entry value='ref_2'>second entry</entry>
    <entry value='ref_3'>third entry</entry>
  </menu>
  <menu name='submenu-1'>
    <entry value='ref_4'>first entry in submenu</entry>
  </menu>
>/menus>
    

<?xml version="1.0" encoding="UTF-8"?>
<uriList>
  <item>
    <screenName>Opera</screenName>
    <uri>http://www.opera.com</uri>
    <guid>100</guid>
    <icon>../theme1/img/Opera.png</icon>
    <menupriority>490</menupriority>
  </item>
</uriList>

<?xml version="1.0" encoding="UTF-8"?>
<services>
  <url serviceid="200">fortuneService/fortuneService.html</url>
  <url serviceid="201" activeFrontpage="true" type="persistentService">Frontpage/newFrontpage.html</url> 
</services>
    

<?xml version="1.0"?>
 <serviceDefinition>
  <name>GoogleSearch</name>
  <guid>8f74c420-cc29-11d9-8cd5-0800200c9a66</guid>
  <screenName>Google</screenName>
  <author>Opera Software ASA</author>
  <javascriptNS>GoogleSearch</javascriptNS>
  <generatedEvents></generatedEvents>
  <supportedEvents></supportedEvents>
  <icon>../theme1/appgridIcons/appgridIcon14.png</icon>
  <menupriority>665</menupriority>
 </serviceDefinition>
    

var stateData = "<prefs><pref key='subscribedFeeds' expiresAt='" 
stateData += new Date(2010, 0, 1).toGMTString() + "'>" + data + "</pref></prefs>";
var msg = myService.createMessage();
msg.addMember("StoreStateRequest", stateData);
//msg.addMember("SetStateRequest", "subscribedFeeds=" + data);
 msg.send();

var msg = myService.createMessage();
msg.addMember("GetStateRequest", "readItems");
msg.send();

this.onMessageReceived = function(message) {
  if (message.containsMembers("GetStateResponse")) {
    var data = message.getMember("GetStateResponse");
    var begin = -1, key = "", val = "";
    if (data != "") {
      begin = data.indexOf("=");
    }
    if (begin > -1) {
      key = data.substr(0, begin);
      val = data.substr(begin + 1, data.length);
    }

    switch (key) {
      case "subscribedFeeds":
        var subscribedFeeds = [];
        subscribedFeeds = val.split(myDelimiter);
        break;
      defalt:
      	alert("Received unknown state key");
    }
  }
}

class O2_Command {
  void execute()
}

class O2_MenuController {
  void addMenu(<String> menuId)
  void callAfterClose(<Function> functionRef)
  void callBeforeOpen(<Function> functionRef)
  void cleanup()
  void closeWithOpenButton(<boolean> value)
  object getItem(<String> itemId)
  boolean isOpen()
  void setActionOnItem(<O2_Command> action, <String> itemId)
  void setActiveMenu(<String> menuId)
  void setCancelText(<String> text)
  void setCenterText(<String> text)
  void setOpenText(<String> text)
  void setPriority1Text(<String> text)
  void setPriority2Text(<String> text)
}

class O2_MenuItem {
  void  addChild(<String> text, <String> itemId, 
            <O2_Command> action, <boolean> enabled, 
            <String> className)
  void  disable()
  void  enable()
  void  removeChild(<String> itemId)
  void  setAction(<O2_Command> action)
}

class  O2_DialogController {
  object addDialog(<String> dialogId, <String> text, <String> type,
                   <String> priority1Text, <String> priority2Text,
                   <O2_Command|function> actionFalse, <O2_Command|function> actionTrue,
                   <Array> labelInputs, <String> additionalClassname)
  void   callAfterClose(<function> function)
  void   callBeforeOpen(<function> function)
  void   closeDialog()
  void   setDefaultCancelText(<String> text)
  void   SetDefaultCenterText(<String> text)
  void   SetDefaultOKText(<String> text)
  void   SetDefaultPriority1Text(<String> text)
  void   SetDefaultPriority2Text(<String> text)
}

<?xml version="1.0"?>
<themes>
  <heading>Theme Selector</heading>
  <theme>
    <name>Opera</name>
    <description>Opera standard theme.</description>
    <previewicon>opera/themeThumb.png</previewicon>
    <stylebase>opera/style.css</stylebase>
  </theme>
</themes>

class Opera
bool register(DOMString serial)

   ele = createElement("li");
   ele.counter = 4;
   ele.onclick = function() { myfunc(this.counter) };
   

   function SomeClass(valueAttrib)
   {
      this.value = valueAttrib;
   }
   SomeClass.prototype.toString = function() { return this.value; }
   

   function SomeClass()
   {
   }
   SomeClass.prototype.public = function() { return "I'm public"; }

   function SomeClass()
   {
      var private = function() { return "I'm private";}
   }
   

   function SomeClass()
   {
      this.privileged = function() { return "I'm privileged"; }
   }
   var o = new SomeClass();
   o.privileged(); // allowed
   o.privileged = function() { return "This is not allowed"; } // not allowed
   

   function SomeClass() {}
   SomeClass.static = function() { return "I'm static";}
   SomeClass.static(); // works fine
   

   document.addEventHandler("click", function(ev) { 
     alert(ev.target + " was clicked") 
   }
   

   function F()
   {
      var self = this;
      var handler = function() { self.handleMore(); }
      this.timeout = function()
    setTimeout(handler, 1000);

     this.handleMore = function() { alert("handled") 
  }

   var mySingleton = new function() { ... }