Menus and Toolbars

Some applications require menus for common operations like File, Save, Print and so on. Although rarely used, Aria provides a means to include a menu bar and a simple mechanism for defining the content of that menu.

Creating a Menu

In the XML page descriptions menus can be added by inserting an MenuBar element. The menu bar element can contain Menu elements which in turn can contain MenuItems . For the Menu and MenuItem elements the content attribute is used as the menu text. A MenuItem without a content attribute will be added as a menu separator. The content of the menu can be the key into the language resource bundle for the current application language.

Creating a simple menu

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <Page>
   <MenuBar>
     <Menu content="File">
       <MenuItem name="newMenu" content="New..."/>
       <MenuItem/>
       <MenuItem name="saveMenu" content="Save"/>
     </Menu>
   </MenuBar>		
 </Page>

An important consideration when creating menus is the lifecycle of a menu. While created as part of a page a menu does not come and go with the defining page but instead lives and is displayed for the duration of the application. Only one instance of the menubar is ever created, although items may be added to the menu at any stage.

A menu is an application wide component and is defined once for the application. One useful way of reinforcing this is to include the menu in the start page rather than inserting the menu definition directly as above.

Looking at amore complicated scenario a menu can include sub menus and can be composed of menus contributed by multiple pages (changing with the page context), however the editor does not yet support sub menu creation. A menu with sub menus is described below

A menu with sub menu items

 <Page layout="Border"> 
   <MenuBar> 
 
     <Menu content="File"> 
       <MenuItem content="New Country..." image="menu/new.png"/> 
       <MenuItem/> 
       <MenuItem content="Open Country..." image="menu/open.png"/> 
       <MenuItem/> 
       <MenuItem content="Save Coutry" image="menu/save.png"/> 
       <MenuItem content="Save Coutry As..." image="menu/saveas.png"/> 
       <MenuItem/> 
       <MenuItem name="exitMI" content="Exit" image="menu/exit.png"/> 
     </Menu> 
 
     <Menu content="Country"> 
       <MenuItem name="belgiumMI" content="Belgium" image="menu/belgium.png"/> 
       <MenuItem name="englandMI" content="England" image="menu/england.png"/> 
       <MenuItem name="franceMI" content="France" image="menu/france.png"/> 
       <MenuItem name="germanyMI" content="Germany" image="menu/germany.png"/> 
       <MenuItem name="irelandMI" content="Ireland" image="menu/ireland.png"/> 
       <MenuItem name="italyMI" content="Italy" image="menu/italy.png"/> 
       <MenuItem name="netherlandMI" content="Netherland" image="menu/netherland.png"/> 
       <MenuItem name="portugalMI" content="Portugal" image="menu/portugal.png"/> 
       <MenuItem name="scotlandMI" content="Scotland" image="menu/scotland.png"/> 
       <MenuItem name="spainMI" content="Spain" image="menu/spain.png"/> 
       <MenuItem name="switzerlandMI" content="Switzerland" image="menu/switzerland.png"/> 
     </Menu> <
 
     <Menu content="About"> 
       <MenuItem name="applicationMI" content="The Application" image="menu/application.png"/> 
       <MenuItem name="authorMI" content="The Author" image="menu/author.png"/> 
       <Menu content="Help"> 
         <MenuItem name="contentsMI" content="Contents" /> 
         <MenuItem name="faqMI" content="FAQ"/> 
       </Menu> 
     </Menu> 
 </MenuBar> 
 .... 

Hooking up Events

Menu events can be hooked up to response handlers using the same event handling mechanism as used by any other component.

Menu Event Handling

 <Event type="MenuHandler" target="saveMenu" method="doSave"/>
 <Event type="MenuHandler" target="newMenu" method="doNew"/>

When considering the menu lifecycle and the longevity of the menu for conceptual reasons it is worth considering using a menus in conjunction with a frameset so that the menu handlers can be defined as part of a long lived page. Alternatively the menu definition can be declared in a separate XML file and included in another page using the include statement.

Because menus are not owned by a particular page in the application they cannot be looked up in the same way as other components which use the findComponent() method of the Page class. Instead the root menu can be obtained from the Applet for the current project.

Retrieving the application menu

 ProjectManager.getCurrentProject().getApplet().getMenuBar();

If a reference to a named menu item is required, then it's necessary to iterate the menus and find the child whose name corresponds. In a localized application, although the menus will be created automatically with the correct language, if the language is changed and the page manager reset, the menus will need to be reset manually. This is illustrated below.

Localizing a menu

 public class SomePage extends Page {
 
   String[] name = { "mnuFile", "mnuFileNew", "mnuFileSave" };
   String[] tran = { "MNU_FILE", "MNU_NEW_PROJ", "MNU_FILE_SAVE" };
 
   public void changeLanguage()
   {
     JMenuBar mBar = project.getApplet().getMenuBar();
     for ( int i = 0; i < mBar.getMenuCount(); i++ ) {
       iterateMenus( mBar.getMenu( i ) );
     }
   }
 
   private void iterateMenus( JMenu menu )
   {
     setMenuText( menu );
     for ( int i = 0; i < menu.getMenuComponentCount(); i++ ) {
       setMenuText( menu.getMenuComponent( i ) );
     }
   }
 
   private void setMenuText( Component c )
   {
    if ( c instanceof XMenu ) {
       ( ( XMenu ) c ).setText( getText( ( XMenu ) c ) );
     }
   }
 
   private String getText( XMenu menu )
   {
     String name = menu.getName();
     for ( int i = 0; i < names.length; i++ ) {
       if ( name.compareTo( names[ i ] ) == 0 ) {
         return translate( translations [ i ] );
       }
     }
     return menu.getText();
   }
 
 }

Editing menus

In the page editor you can load pages with menus and preview those menus by clicking the Show Menu button on the designers toolbar. The preview relies on there being a component or page selected as the menu is specific to the current page.

You can switch back and forth to the XML and edit the menus but the editor support is incomplete (as of version 2.0.6) as it does not provide an interactive way of setting the menu details such as the event response methods or menu texts.

Using multiple menus

[since Aria 2.0.7]

Since menus are defined on a page by page basis it is possible to define menus on more than one page, and since the menus are declared as children of a menu bar object it is worth note how this behaves in practice.

When a page is parsed the menu it declares is instantiated along with a menu bar, this new menu bar is given the name of the page within which it was declared. Once a menu bar has been created an attempt is made to set it as the applications menu bar. On the first occassion that this happens the new menu bar becomes the application's menu bar. Subsequently the menus belonging to the new menu bar are attached to the existing menu, thereby appending the new menus to the existing application menu bar.

If a page is reloaded (which might perhaps occur during the localization process) the menus will again be created using this process with the exception that the first page with a menu bar is treated specially and causes the existing menubar to be replaced.

Creating context sensitive menus

Some applications may require some menus or individual menu items to be context sensitive and why there is no mechanism to setup up such context sensitivity declaratively there are a number of options available.

Firstly, within the application's Java code it is possible to interact with the menus in the normal way. The menu bar can be retrieved from the application via the normal static methods (depending upon the widget set employed, in Swing for example you would call org.formaria.Applet.getMenuBar() ).

Secondly the menuHandler could be defined as an evaluated attribute, referring to a method in an instance of an javax.swing.Action object. The Action interface can then be used to set the enabled and disabled state of the menus. Check out the goodies section of the Xoetroep website for some more details.

Toolbars

Toolbars can be added to an application as part of the frames setup. A toolbar is considered to be a special type of page, loaded as part of the frameset.

The frameset can contain any number of target areas plus a toolbar element:

Setting up a toolbar in the frames.xml file

 <FrameSet 
       config="(COLUMN (ROW weight=1.0 left (COLUMN middleTop content middleBottom) right) bottom)">
 	<Toolbar name="toolbar" constraint="NORTH" content="toolbar"/>
 	<Frame name="left" constraint="left" content="left" icon="wi0062-16.png" sidebar="west" 
       title="A car to stir the emotions"/>
 	<Frame name="right" constraint="right" content="right" title="Specifications" icon="wi0126-16.png" 
       sidebar="east"/>
 	<Frame name="middleTop" constraint="middleTop" content="middleTop" title="Citroen C6" 
       icon="wi0124-16.png" sidebar="west"/>
 	<Frame name="middleBottom" constraint="middleBottom" content="middleBottom" 
       title="Engines" icon="wi0122-16.png" sidebar="south"/>
 	<Frame name="content" constraint="content" content="Welcome" title="Gallery" 
       icon="ac0036-16.png" sidebar="west"/>
 	<Frame name="bottom" constraint="bottom" content="bottom" title="Dealers" 
       icon="wi0063-16.png" sidebar="south"/>
 </FrameSet>

The toolbar itself is specified as any other page in your application. For the example shown above the toolbar.xml file contains the following:

toolbar.xml

 <Page layout="Flow" class="org.formaria.swing.toolbar.Toolbar" style="toolbar">
   	<Guides width="640" height="480" vert="" horz=""/>
   	<Layout alignment="left"/></P>
 	<Components>
     		<ToolbarButton name="FileBtn" content="File" style="toolbar" icon="wi0063-16.png"/>
     		<ToolbarButton name="CutBtn" style="toolbar" icon="wi0122-24.png"/>
     		<ToolbarButton name="CopyBtn" style="toolbar" icon="wi0064-24.png"/>
     		<ToolbarButton name="PasteBtn" style="toolbar" icon="wi0009-24.png"/></P>
   	</Components>
 </Page>