WidSets for Rookie EP 6 : Softkey Menu

From Forum Nokia Wiki

This article is archived because it is not considered relevant for third-party developers creating commercial solutions today. The article is believed to be still valid for the original topic scope.

Introduction

This page will describe you how to manage softkey menu from simple menu to complicated menu.

Softkey Menu Basic

In WidSets, there are 3 softkey menu positions. Each position has constant like shown below.

Left Softkey : SOFTKEY_OK
Middle Softkey (or Joystick in practical) : SOFTKEY_MIDDLE
Right Softkey : SOFTKEY_BACK

To define softkey menu, you need to know MenuItem object and getSoftKey callback function.

MenuItem is a class that represent an individual item on a Menu. To construct, you have to follow this template.

  MenuItem <menu_item_variable> = new MenuItem(<command_uid>, <text>);

Here is an example of MenuItem construction. MENU_BACK is object for Right Softkey and have text "Back".

  const int CMD_BACK = 1;

  MenuItem MENU_BACK = new MenuItem(CMD_BACK, "Back");

getSoftKey function will be called by framework for each softkey position by passing softkey position constant described above via key argument. So we will check this key parameter and return the correct MenuItem.

  const int CMD_BACK = 1;

  MenuItem MENU_BACK = new MenuItem(CMD_BACK, "Back");

  ...

  MenuItem getSoftKey(Shell shell, Component focused, int key)
  {
    if (key == SOFTKEY_BACK) {
      return MENU_BACK;
    }
    return null;
  }

Here is the result of upper code.

You can do the same thing to define softkey for another position.

  const int CMD_BACK = 1;
  const int CMD_OPTIONS = 2;
  const int CMD_SELECT = 3;
  
  MenuItem MENU_BACK = new MenuItem(CMD_BACK, "Back");
  MenuItem MENU_SELECT = new MenuItem(CMD_SELECT, "Select");
  MenuItem MENU_OPTIONS = new MenuItem(CMD_OPTIONS, "Options");

  ...

  MenuItem getSoftKey(Shell shell, Component focused, int key)
  {
    if (key == SOFTKEY_BACK) {
      return MENU_BACK;
    } else if (key == SOFTKEY_OK) {
      return MENU_OPTIONS;
    } else if (key == SOFTKEY_MIDDLE) {
      return MENU_SELECT;
    }
    return null;
  }

And here is the result.

Handle Softkey Action

To handle softkey action, you need to know actionPerformed callback function. This function will be called with menu id passed in action argument when user press any softkey. For example, if user press Back (Right Softkey), actionPerformed function will be called with action value equals to CMD_BACK.

  void actionPerformed(Shell shell, Component source, int action)
  {
    //when CMD_BACK event comes in, pop the current shell (this widget)
    if (action == CMD_BACK) {
      popShell(shell); 
    }
  }

So, if user press Back, the widget will be popped out and go back to Dashboard.

Popup Menu

Last section explained you how to define softkey menu. But if you want to create popup menu like the picture below, how to implement it?

Implementation

It's quite similar to define softkey menu. For this thing, you have to use getMenu callback function and Menu object.

First, add menu ids and Menu object definition.

 const int CMD_OPEN = 4;
 const int CMD_MORE = 5;
 const int CMD_HOME = 6;
 const int CMD_HELP = 7;
 const int CMD_SETTINGS = 8;
 const int CMD_EXIT = 9;
 
 Menu m = new Menu()
              .add(CMD_OPEN, "Open")
              .begin(CMD_MORE, "More")
                 .add(CMD_HOME, "Homepage")
                 .add(CMD_HELP, "Help")
                 .add(CMD_SETTINGS, "Settings")
              .end()
              .add(CMD_EXIT, "Exit");

add command is used for adding menu item while begin and end are used for define menu that contains submenu, add command inside this part will be item in the submenu.

And then define getMenu callback function. (getMenu function will be called when the popup menu has been launched.)

  Menu getMenu(Shell shell, Component focused)
  {
    return m.reset();
  }

Now, how to launch this popup menu? You need to change first argument of wanted softkey position’s MenuItem object to OPEN_MENU. (It's predefined menu action id, so you don't need to define it yourself)

 MenuItem MENU_OPTIONS = new MenuItem(OPEN_MENU, "Options");

Now, let's try your code. Here is the result.

Menu Handling

You can handle these menu events in the same way as softkey menu.

 void actionPerformed(Shell shell, Component source, int action)
 {
   //when CMD_BACK event comes in, pop the current shell (this widget)
   if (action == CMD_BACK) {
     popShell(shell); 
   } else if (action == CMD_EXIT) {
     popShell(shell); 
   }
 }

Other Predefined Menu Action IDs

You may curious that are there any other predefined menu action ids except OPEN_MENU, right? The answer is yes. There are few more such as:

OPEN_SETTINGS – Show Settings page

OPEN_HELP – Show Widget Help

OPEN_HOME – Open Widget Home Page

You can test these predefined menu action ids by modify your code like shown below and test by choose More->Homepage, More->Help and More->Settings.

 Menu m = new Menu()
              .add(CMD_OPEN, "Open")
              .begin(CMD_MORE, "More")
                 .add(OPEN_HOME, "Homepage")
                 .add(OPEN_HELP, "Help")
                 .add(OPEN_SETTINGS, "Settings")
              .end()
              .add(CMD_EXIT, "Exit");

OPEN_LINK – No information right now

Menu Item Disabling

You can disable using enable command after m.reset() in getMenu callback function.

 Menu getMenu(Shell shell, Component focused)
 {
   return m.reset().enable(CMD_OPEN, false)
                   .enable(OPEN_SETTINGS, false);
 }

You are also able to define condition for enable/disable menu item.

 Menu getMenu(Shell shell, Component focused)
 {
   return m.reset().enable(CMD_OPEN, false)
                   .enable(OPEN_SETTINGS, isOnline());
 }

isOnline() is function used for checking WidSets online status. And here is the result.

Dynamic Menu

You are also able to change softkey menu dynamically by set the condition in getSoftKey and then call shell.updateMenu(); to update softkey menu.

 boolean mode = false;
 
 ...
 
 Shell openWidget()
 {
   //instantiate maximized view when user opens this widget
   Flow view = createView("viewMaxi", getStyle("bg"));
   mode = true; 
   return new Shell(view);
 }
 
 MenuItem getSoftKey(Shell shell, Component focused, int key)
 {
   //return the key we want to display at position=SOFTKEY_BACK
   //this usually is the Right Soft Button (RSB), for other key
   //positions return null, as we don't want other keys
   if (key == SOFTKEY_BACK) {
     return MENU_BACK;
   } else if (key == SOFTKEY_OK) {
     if (mode)
       return MENU_OPTIONS;
     else
       return null; 
   } else if (key == SOFTKEY_MIDDLE) {
     return MENU_SELECT;
   }
   return null;
 }
 
 ...
 
 void actionPerformed(Shell shell, Component source, int action)
 {
   //when CMD_BACK event comes in, pop the current shell (this widget)
   if (action == CMD_BACK) {
     popShell(shell);
   } else if (action == CMD_SELECT) {
     mode = !mode;
     shell.updateMenu();
   }
 }

Options menu (left softkey) visibility will be toggled by pressing Select menu (middle softkey). Here is the result.

Hiding Softkey Area

You can hide softkey area in order to develop Full Screen application. To do that, you have to modify openWidget() function.

 Shell openWidget()
 {
   //instantiate maximized view when user opens this widget
   Flow view = createView("viewMaxi", getStyle("bg"));
   Shell shell = new Shell(view);
   shell[1].setFlags(1);
   return shell;
 }

An emphasized line is part of code that used for hiding softkey area. Here is the result.

Code Snippet

You can download source code for this tutorial from File:WidSets Example Softkey Menu.zip

Community: Wiki