Rich UI menu

A Rich UI menu widget defines a menu, which is displayed as a single, top-level entry, such as File.
The menu has subordinate menu items that each can provide additional options. To create a menu bar, you can declare a box widget that contains a series of menus:
menuBar Box{ font = "Arial", children = [
   fileMenu,
   otherMenu,
   helpMenu 	]};
You might place the menu bar in a larger box, which includes the overall Web page. Here is partial code from a later example:
handler MyHandler type RUIhandler{initialUI =[ui], onConstructionFunction = start}

ui Box{columns = 1, margin = 12, background = "#eeeeee", 
   children =[ menubar,
               new Box{ borderStyle = "solid", borderColor = "orange", borderTopWidth = 25,
               padding = 11, children =[changeTextBox]}
             ]};
You specify an array of menu items for each menu, and each menu item references (at most) two functions:
For example, here is the array of items for the file menu, followed by the file menu declaration:
fileMenuItems menuItem[] =[                    
   new MenuItem{item = "Clear", itemType = MenuBehaviors.simpleText, itemAction = menuAction},
   new MenuItem{item = "Type", itemType = MenuBehaviors.simpleText, itemAction = menuAction}];

fileMenu Menu{menubehaviors ::= MenuBehaviors.BasicMenu, title = "File", 
              options = fileMenuItems, onMenuOpen = closeMenu};

For information about supported properties and functions, see "Widget properties and functions."

If you use this widget, you must use the following statements:
import com.ibm.egl.rui.widgets.Menu;
import com.ibm.egl.rui.widgets.MenuBehaviors;
import com.ibm.egl.rui.widgets.MenuItem;
Remember: Before you declare the menu in which items are displayed, you must declare the set of menu items.

MenuItem

The fields for the MenuItem type (a Record part) reference the item-type and item-action functions. The MenuItem type has the following fields:
id
An optional value to associate the menu item with a CSS entry.
item
A value that is passed to the item-type function. Rich UI provides a few functions and you can code your own; but assuming you use the existing choices, the value of the item property is one of the following values:
  • A string to display as a submenu item. Only in this case do you specify an item-action function in the menu-item declaration.
  • A widget to display as a submenu item.
  • An array that is composed of a submenu title and an array that references a set of subordinate submenu items. The following fragment shows this alternative and is from a later example:
    new MenuItem{item =["Special", [myTimeItem, myReadOnlyItem]],
                 itemType= MenuBehaviors.subMenu }];
itemType
A reference to the item-type function.
Rich UI provides three functions that allow for the options that are described in relation to the item property:
  • Use the simpleText function if item is a string to display
  • Use the widgetItem function if item is widget
  • Use the subMenu function if item is an array of string and subordinate submenu items

All of those functions are in the MenuBehaviors Rich UI library.

itemAction
A reference to the item-action function. Specify this value only if the value of the item field is a string.
The item-type function has the characteristics that are defined in the following Delegate part:
Delegate 
   MenuItemType(newItem any in, itemAction MenuItemSelection, parentMenu Menu in) 
      returns (any) 
end
newItem
The item that you specify when you declare the menu item
itemAction
A reference to the item-action function, as is always required in the item-type function.

In general, the MenuItemSelection Delegate part describes the item-action function, as noted later.

parentMenu
The menu that contains the menu item
Here is the MenuItemSelection Delegate part, which describes the item-action function:
Delegate MenuItemSelection(parentMenu Menu, item any in) end
parentMenu
The menu that contains the menu item
item
The menu item
The item-action function (in outline) might be as follows:
function menuAction(parentMenu Menu, item any in)
   if(parentMenu == fileMenu)
      case(item as string)
         when("Clear")
            ;
         otherwise
            ;
         end
   else
      if(parentMenu == helpMenu)
         ;
      else
         ; 
      end
   end
end

Menu

The fields for the Menu type are as follows:
menuBehaviors
A reference to a function that is invoked during the creation or re-display of the menu, so that styles and functionality are applied to the menu. You can add the reference to the menuBehaviors array by using the append syntax (::=). You can have repeated entries (the syntax is as shown in the example), and when a user selects a menu, the referenced functions run in array-element order. In the example, the menuBehaviors property references the basicMenu function, which is available in the MenuBehaviors Rich UI library. You can use the function basicMenu directly or can use it as a basis for your own function.

The MenuBehaviors Delegate part describes the characteristics of the function that is referenced. The Delegate part is described later.

In the menu declaration, list the behaviors property before the other properties.

title
The string to display
options
An array of menu items
onMenuOpen
A reference to a function that runs when the user selects the menu. The function has no return value and has a single parameter of type Menu and qualifier IN. In the following example, when the user selects one menu, any other menu that is open closes:
function closeMenu(keepOpen Menu IN)
   if(keepOpen != fileMenu)
      fileMenu.hideOptions(false);
   end
   if(keepOpen != otherMenu)
      otherMenu.hideOptions(false);
   end
   if(keepOpen != helpMenu)
      helpMenu.hideOptions(false);
   end
end
This code shows the MenuBehavior Delegate part, which describes each function that is invoked in response to a menu selection at run time:
Delegate 
   MenuBehavior(menu Menu in, titleBar TextLabel, optionsBox Box, options MenuItem[]) 
end
menu
The menu
titleBar
A text label that contains the menu title you assigned
optionsBox
A box that contains a child for every item in the menu. The basicMenu function assigns rules for highlighting those children in response to mouse movements at run time:
for (index int from 1 to optionsbox.children.getSize() by 1)
   widget Widget = optionsBox.children[index];
   widget.onMouseOver ::= highlight;
   widget.onMouseOut ::= removemenuhighlight;
end
options
An array of the menu items.
The layouts() function resets widget behaviors, as described in the following rules:
  • When you declare a menu, ensure that you list the menuBehaviors property first.
  • When you write statements in functions, if you change the value of the menuBehaviors property, invoke the menu-specific layouts() function to reset the widget.

Example

You can bring the following example into your workspace to see the relationships that are described in this topic.

package myPkg;

import com.ibm.egl.rui.widgets.Box;
import com.ibm.egl.rui.widgets.CheckBox;
import com.ibm.egl.rui.widgets.HTML;
import com.ibm.egl.rui.widgets.Menu;
import com.ibm.egl.rui.widgets.MenuBehaviors;
import com.ibm.egl.rui.widgets.MenuItem;
import com.ibm.egl.rui.widgets.TextField;
import egl.ui.rui.Event;

handler MyHandler type RUIhandler{initialUI =[ui], onConstructionFunction = start}
    {}

ui Box{columns = 1, margin = 12, background = "#eeeeee", 
         children = [
         menubar,
         new Box{
         borderWidth = 2, borderStyle = "solid", borderColor = "orange", 
         borderTopWidth = 50, padding = 11, 
         children =[changeTextBox]}]};

   menuBar Box{font = "Arial", children =[fileMenu, otherMenu, helpMenu]};
   changeTextBox TextField{text="here"};
   readonlyCheck CheckBox{Text = "Read Only", onChange::= setReadOnly};

    
   myTimeItem menuItem{
      item = "Time?",
      itemType = MenuBehaviors.simpleText,
      itemAction = tellTime };    

   myReadOnlyItem MenuItem { 
      item = readOnlyCheck, 
      itemType = MenuBehaviors.widgetItem };

   fileMenuItems menuItem[] =[                    
                   new MenuItem{item = "Clear", 
                                itemType = MenuBehaviors.simpleText, itemAction = menuAction},
                   new MenuItem{item = "Type", 
                                itemType = MenuBehaviors.simpleText, 
                                itemAction = menuAction} ];

   otherMenuItems menuItem[] =[
                   new MenuItem{item =["Special", [myTimeItem, myReadOnlyItem]],
                                itemType= MenuBehaviors.subMenu }];
        
   helpItems menuItem[] =[new MenuItem{item = "About", 
                                       itemType = MenuBehaviors.simpleText, 
                                       itemAction = showHelp} ];

   fileMenu Menu{menubehaviors ::= MenuBehaviors.BasicMenu, title = "File",
                 options = fileMenuItems, onMenuOpen = closeMenu};

   helpMenu Menu{menubehaviors ::= MenuBehaviors.BasicMenu, title = "Help",
                 options = helpItems, onMenuOpen = closeMenu};

   otherMenu Menu{menubehaviors ::= MenuBehaviors.BasicMenu, title = "Other",
                  options = otherMenuItems, onMenuOpen = closeMenu};

   helpArea HTML{onClick ::= hideHelp, position = "absolute", x = 70, y = 60, 
                 backgroundColor = "lightyellow", width = 400, padding = 11, 
                 borderWidth = 3, borderStyle = "solid", height = 50, 
                 text = "Helpful detail is here. <p>Click this box to continue working.</p>"};

   function start()

   end

   function tellTime(parentMenu Menu, item any in)
      changeTextBox.text = dateTimeLib.currentTime();
   end

   function menuAction(parentMenu Menu, item any in)
      if(parentMenu == fileMenu)
         case(item as string)
            when("Clear")
               changeTextBox.text = "";
            otherwise
               changeTextBox.select();
            end
      else
         if(parentMenu == helpMenu)
            ;
         else
            ;  // parentMenu == widgetMenu
         end
      end
   end

   function setReadOnly(e Event in)
      changeTextBox.readOnly = !(changeTextBox.readOnly);			
   end
       
   function closeMenu(keepOpen Menu in)

      if(keepOpen != fileMenu)
         fileMenu.hideOptions(false);
      end

      if(keepOpen != otherMenu)
         otherMenu.hideOptions(false);
      end

      if(keepOpen != helpMenu)
         helpMenu.hideOptions(false);
      end
   end

   function showHelp(parentMenu Menu, item any in)
      document.body.appendChild(helparea);
   end

   function hideHelp(e Event in)
      document.body.removeChild(helparea);
   end
end

Feedback