The 2 Minute Tutorial

This tutorial will take you through creating a basic command and then cover a simple application with a main menu. First we'll create and configure a basic ActionCommand.

1. Create some configuration

GUI Commands configuration files are just standard Java ResourceBundles. This means you can use any of the standard resource bundle approaches. For this example well stick to the property file variant.

We'll add the following to TutorialCommands.properties.

   hello-world@face.text=_Hello World!!!@control H
   hello-world@face.icon=classpath:images/hello-world.png
   hello-world@face.description=Says hello ($accelerator).

In the above we configure the text, icon and description of the "hello-world" command. The text specifies that 'H' is the mnemonic and "Control H" is the accelerator. The description contains the commands accelerator in parenthesis.

2. Load the configuration

The next step is to load the configuration. GUI Commands allows you to provide just the resource bundle name using the same syntax as ResourceBundle.getBundle(String). You can load as many bundles as you like.

   // load our configuration file
   GuiCommands.load("TutorialCommands");

3. Create the Command

Commands are created by extending ActionCommand and implementing hanldleExecute(). ActionCommands provide many convenience methods such as getInvokerWindow().

   /**
    * A command with the id "hello-world" that displays 
    * a greeting over the current frame.
    */
   public class HelloWorldCommand extends ActionCommand
   {
      public HelloWorldCommand()
      {
         // Our command id is "hello-world".
         super("hello-world");
      }

      /**
       * Say hello
       */
      public void handleExecute()
      {
         Window window = getInvokerWindow();
         JOptionPane.showMessageDialog(window, "Hello World!!!");
      }
   }

4. Use the Command

Finally we instantiate the command and create buttons and menus as required.

   // now create the command.
   HelloWorldCommand helloWorldCommand = new HelloWorldCommand();

   // and ask it for a button and menu item.
   AbstractButton button = helloWorldCommand.createButton();
   JMeuItem menuItem = helloWorldCommand.createMenuItem();

Now you've successfully created and configured a simple command and used it to create a button. The next part of the tutorial will focus on creating using commands in the main menu of basic frame.

A Main Menu Bar Example

In this example we'll create a simple frame and use GUI Commands to create a menu bar.

1. Define our Configuration

   # Create main menu with a "File" sub menu.  You can add other
   # members by separating with a comma.
   # e.g. members=file-menu, edit-menu, glue, help-menu
   group!main-menu@members=file-menu

   # Define the file menu.  We specifiy autoCreate=true so we don't
   # have to explicitly create the file menu group in code.
   group!file-menu@face.text=_File
   group!file-menu@autoCreate=true
   group!file-menu@members=hello-world, separator, exit

   # here's our hello-world command as before.
   hello-world@face.text=_Hello World!!!@control H
   hello-world@face.icon=classpath:images/hello-world.png
   hello-world@face.description=Says world ($accelerator).

   # Lets define an exit command as well.
   exit@face.text=E_xit@alt F4
   exit@face.description=Exit the demo ($accelerator)

2. Create a Panel

Now lets create the panel that defines the HelloWorld command.

   /**
    * A panel that creates and binds a HelloWorldCommand.
    */
   public class HelloWorldPanel extends JPanel
   {
      public HelloWorldPanel()
      {
         // create the press me command
         HelloWorldCommand helloWorld = new HelloWorldCommand();

         // now bind it to the panel to make it available to
         // groups defined in the current frame.
         helloWorld.bind(this);

         // create add a button.
         AbstractButton button = helloWorld.createButton();
         // and add it
         setLayout(new FlowLayout());
         add(button);
      }
   }

The call to bind in the above example allows our command to be discovered by the main menu. We'll cover this a little more in the next section, but for a complete discussion (with diagrams) you can read about Containers and Binding in the user guide.

3. Create our Frame

Now we create a simple frame and insert the above panel into it. In order to create out menu we first construct a CommandContainer and bind it to the frame. This allows all our commands and groups to search the Swing component hierarchy and find the container. Once located the commands and groups find each other and everything automatically updates.

   /**
    * Now we'll create a frame that contains the above panel.
    */
   public class HelloWorldFrame extends JFrame
   {
      private CommandContainer commandContainer;
      private CloseWindowCommand exitCommand;

      public HelloWorldFrame()
      {
         // create a new container for the frame.
         commandContainer = new CommandContainer();
         // bind it so all our commands and groups can find it.
         commandContainer.bind(this);

         // create and bind the exit command.
         exitCommand = new CloseWindowCommand("exit");
         exitCommand.setTargetWindow(this);
         exitCommand.setDisposeOnClose(true);
         exitCommand.bind(this);

         // create and bind the main menu group, once bound it.
         // will automatically find all its members.
         CommandGroup mainMenu = new CommandGroup("main-menu");
         mainMenu.bind(this);

         // now use the group to create and install the menu bar.
         setJMenuBar(mainMenu.createMenuBar());

         // Once our panel is added the HelloWorldcommand will automatically
         // add itself to the container and our menus will update.
         getContentPane().add(new HelloWorldPanel());
      }
   }

And finally the main method.

   public static void main(String[] args)
   {
      try
      {
         GuiCommands.load("TutorialCommands");
      }
      catch (ParseException e)
      {
         throw new RuntimeException("Parse failure", e);
      }

      HelloWorldFrame frame = new HelloWorldFrame();
      frame.setSize(225, 140);
      frame.setLocationRelativeTo(null);
      frame.setVisible(true);
   }

Here's what it looks like

    

A Note on Binding

GUI Commands supports direct container binding for cases where you want to keep your commands isolated from your view code. In this case you simply bind directly to the container, but you'll need to manage your container hierarchy independantly of the Swing component hierarchy.

For more information on binding please read the Containers and Binding section of the User Guide.

The example belows shows direct container binding:

   // Create a conatiner...
   CommandContainer commandContainer = new CommandContainer();

   // ...and bind directly to it
   myCommand.bind(commandContainer);

What's Next?

Why not try the demo, or check out the User Guide or browse the Javadoc.