CMenu - custom menu component

General

For the easy creation of menu bars, there is a convenience component named CMenu (the 'C' stands for 'Custom' here, a convention which is also used in the SWT libraries). The CMenu reads all information it needs from an XML configuration file. You can specify the configuration file with the setConfigFile( java.io.File ) method.

In the configuration file, every menu item to be added to the menu bar has an entry. Typically, you will want to configure the labels of the items, the dropdown menu to which they are attached, and a command that implements what happens when the item is selected by the user.

(You are free to create your dropdown menus in other ways: the CMenu component is just a convenient way and reflects some recommended practices. If you like, you may create menus in W4T Eclipse by adding items to a MenuBar, or add them programmatically, e.g. if you want to fill in the menus dynamically from a database.)

API documentation

The API documentation for CMenu can be found here.

Format of the configuration file

A configuration file for CMenu should look like this:


    <CMenu>
   
      <menuEntry>
        <!-- entry for a menu item in Menu 'File' -->
        <menu>File</menu>
         <label>File</label>
        <id>FILE_QUIT</id>
        <command>com.and.go.FileQuitCommand</command>
      </menuEntry>
  
      <!-- more entries go here -->
  
    </CMenu>
  

It thus specifies the name of the menu and the text of the menu item as well as information about commands that are triggered if the user selects it.

Adding commands

How do I trigger a specific command from a menu item? There are two possible situations:

a) You have already a command waiting in the command repository, probably because you created one somewhere else in your application and added it to the repository like this:

    Command myCommand = new MyCommand();
    W4TContext.addCommand( "myCommand", myCommand );
  
If you did this, the command sits and waits and you only need to tell the CMenu the key which you used to add it to the repository (in this case simply "myCommand"), just leave the 'command' element empty:
    <menuItem>
      <menu>myMenu</menu>
      <label>myItem</label>
      <!-- specify the id under which the  
          command is known in the W4TContext -->
      <id>myCommand</id>   
      <!-- leave this empty  -->
      <command></command>    
    </menuItem>
  
The CMenu initializes then the menu item named "myItem" in the "myMenu" menu in a way that the MyCommand is processed whenever the user selects the item.

b) If you want your command to be created and added to the repository when the CMenu is initialized, specify a fully qualified class name in the CMenu.xml. The CMenu will then try to instantiate the command (it must have a parameterless constructor then, of course) and add it to the command repository. It uses the id you specified as key for the W4TContext.

     <menuItem>
       <menu>myMenu</menu>
       <label>mySecondItem</label>

       <!-- specify the id under which the command 
            should be added to the W4TContext -->
       <id>mySecondCommand</id>                 

       <!-- name the command's class here  -->
       <command>com.mand.CommandName</command>  
     </menuItem>
   

Remember the difference: in case a), you have to create the command elsewhere and add it to the W4TContext's command repository, in case b) this job is done for you by the CMenu.

Case a) comes in handy when you need to create commands which take an argument in the constructor, or when you use the same commands at different places (e.g. from both a CMenu and a CToolBar). Case b) is useful when you use the commands only for menu items and nowhere else.

Styling

The style settings that can be made on a CMenu are delegated to the encapsulated MenuBar.

If you want to change the colors and fonts of the MenuBar, have a look at the API documentation for the package com.w4t.dhtml.menustyle.

In general, the style objects defined in that package allow to set whatever style settings make sense on the various areas of the menu bar, menu popup areas, and menu items. The image below shows which areas can be configured with which style objects of com.w4t.dhtml.menustyle: