CToolBar - custom toolbar component

General

For the easy creation of toolbars, there is a convenience component named CToolBar (the 'C' stands for 'Custom' here, a convention which is also used in the SWT libraries). The CToolBar 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 toolbar button to be added to the toolbar has an entry. Typically, you will want to configure the images and tooltip texts on the buttons, and a command that implements what happens when the button is pressed by the user.

API documentation

The API documentation for CToolBar can be found here.

Format of the configuration file

A configuration file for CToolBar should look like this:


    <CToolBar>
  
      <toolBarButton>
        <!-- entry for a button -->
        <image>images/myImage.gif</image>
        <toolTip>Text that appears on mouse over.</toolTip>
        <id>NEW_FILE</id>
        <command>com.and.go.NewFileCommand</command>
      </toolBarButton>
  
      <!-- more entries go here -->
  
    </CToolBar>
  

It thus specifies the image name, tooltip text and information about commands that are triggered by the toolbar buttons.

Adding commands

How do I trigger a specific command from a toolbar button? 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 CToolBar the key which you used to add it to the repository (in this case simply "myCommand"), just leave the 'command' element empty:
    <toolBarButton>
      <image>images/myApp/anyImage.gif</image>
      <toolTip>Some text</toolTip>
      <!-- specify the id under which the  
          command is known in the W4TContext -->
      <id>myCommand</id>   
      <!-- leave this empty  -->
      <command></command>    
    </toolBarButton>
  
The CToolBar initializes then the toolbar button with the specified image and tooltip text in a way that the MyCommand is processed whenever the user selects clicks on it.

b) If you want your command to be created and added to the repository when the CToolBar is initialized, specify a fully qualified class name in the configuration file. The CToolBar 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.

     <toolBarButton>
       <image>images/myApp/anyImage.gif</image>
       <toolTip>Some text</toolTip>

       <!-- 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>  
     </toolBarButton>
   

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 CToolBar.

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 toolbar buttons and nowhere else.