Bean Extender: Guide to Dip Creation Wizard Walk-Through


The Walk-Through Overview

This document will walk a user through the creation of a dip using the Dip Creation Wizard. Screenshots will show what needs to be entered on each notebook page, along with some accompanying discussion. This document will take one through the creation of the Splash Screen Dip, available in C:\Extender\src\com\ibm\beans\samples\dips\splash (where C:\Extender is the directory in which BeanExtender is installed). A Dip Creation Wizard model file, splash.wiz, is available which can be loaded into the Dip Creation Wizard to cause all of the settings shown below to be selected. For further information on the specifics of each control available on each notebook page of the Dip Creation Wizard, see the Dip Creation Wizard.

Before continuing with the Walk-Through, please verify that you are configured correctly. The following needs to have been done for the Dip Creation Wizard to have been configured correctly:

  1. You must have downloaded and installed a copy of the Beanery from alphaWorks

  2. You must have downloaded a copy of Bean Extender, and installed it using the instructions in the README

  3. CLASSPATH needs to include the Bean Extender jar files, and the Beanery jar files, and the DipWizard jar:
        C:\extender\jars\runtime.jar;C:\extender\jars\develop.jar;
        C:\extender\jars\awidgets.jar;C:\extender\working;
        C:\beanery\Beanery.jar;C:\beanery\sk.jar;
        C:\extender\jars\dipWizard.jar
    
    Where C:\extender represents the path where you installed Bean Extender, C:\extender\working represents the working directory you set up while following the instruction in the README, and C:\beanery represents the path where you installed the Beanery.

Explanation of the Splash Screen Dip

The sample dip we will create in the following section is a simple dip that causes a dialog, containing text and/or an image, to be displayed just before the bean to which the dip is applied gets displayed. Such a "splash" dialog could contain legal information, reminders to register software, advertisements, etc. The dialog contains an instance of the ImageViewer bean (from C:\Extender\src\com\ibm\beans\samples\media), which can display static or animated gif images as well as jpg images, and contains a TextArea and a button to dismiss the dialog.

The new Splash Screen dip will have following behavior:

For further information about the Splash Screen Dip, see the Splash Screen Dip in the Bean Extender Guide to Features.

What to do on each screen

The "Dip" page

The settings on this page determine the basic policy of the dip, providing the information necessary to implement the methods from the DipInfo interface in the com.ibm.beans.dip package. The information on this page also determines the location and filenames of the emitted files and the type of beans to which this dip can be applied.

The "Listeners" page

The settings on this page specify that the dip is only interested in receiving notification of method calls on its dippable bean, meaning that the dip will need to implement the DipMethodCallListener interface. Furthermore, the dip is only interested in receiving a method call notification when the addNotify() method of its dippable bean is invoked (and not when other methods are invoked). Notice that the list of methods displayed here are obtained by introspecting the class (or interface) entered in the "Applicable To" entry field on the "Dip" page. All methods obtained through this introspection are displayed, except the final, static, native, or private methods.

The "Methods" page

On this page, the user can specify additional methods to be emitted. The Splash Screen dip chooses to emit the constructor and readObject methods in order to perform necessary initialization. The createImplementation method is also emitted to verify that every bean to which the dip is applied is a descendant of java.awt.Component (otherwise it rejects being applied to the bean). The includeInMorphedClass method is also emitted to specify that only the addNotify() method of the dippable bean needs to be overridden when morphing a candidate bean with this dip listed as a pre-dip.

The "Properties" page

On this page, the user specifies that this dip will have two properties: noticeText and imageName. The noticeText property is a String that will be displayed in the TextArea on the splash dialog. The imageName property is a String containing the name of a gif or jpg image (either from a file somewhere on disk or from a resource, such as an image within a jar file) to be displayed on the splash dialog. If either property is unspecified, then its corresponding widget will not be part of the splash dialog. If both are unspecified, then the dialog will not be displayed at all.

The "Events" page

On this page, the user specifies that this dip will listen for action events, meaning that the dip must implement the ActionListener interface. The action events will be generated by the dismissal button on the dialog. In response to receiving an action event, the splash dialog will be dismissed.

The "BeanInfo" page

Here, the user specifies that they would like a Customizer to be generated, which will contain controls for setting each of the two properties specified on the "Properties" page.

The "Settings" page

Here, the user can enter legal information that will be emitted into the generated source files. Also, setup information, such as directory locations, can be entered. Text entered in the "Package prefix" field will be used as the default package on the "Dip" page. This field can be modified so that the dip will be isolated to its own package. Text entered in the "Notice text" field will be emitted into the top of the generated source files. This text should be in Java comments to prevent compilation errors.

The Guide View

You can go to the Guide View and look at a preview of the SplashScreenDip.java file that will be generated, which will look like the following:

You can also look at a preview of the HTML documentation that will be generated, which will look like the following:

After you are satisfied with what you see in the Guide View, you can choose the "Generate" menu item to cause all of the listed files to be emitted into the directory specified in the "Base directory" field of the "Settings" page.

Additional code required after code generation

After generating the source files for the Splash Screen Dip, you will need to add the actual logic to accomplish the desired task - in this case, to create and display the splash dialog. The following code needs to be entered in the handleMethodCall method, right after the "Place code here for responding to 'addNotify()'" comment:

   if (noticeText.equals("") && imageName.equals("")) return;

   parentFrame = null;
   Component parent = myDippableBean;
   while ((parentFrame==null) && (parent!=null)) {
      if (parent instanceof Frame) {
	 parentFrame = (Frame) parent;
      } else {
	 parent = parent.getParent();
      } /* endif */
   } /* endwhile */
   if (parentFrame==null) parentFrame = new Frame("Splash Screen");

// splashWindow = new Window(parentFrame); //this causes no border - looks embedded in Layout view

// splashWindow = new Dialog(parentFrame, "Splash Screen", true); //being modal causes deadlock
   splashWindow = new Dialog(parentFrame, "Splash Screen");

   if (!imageName.equals("")) {
      ImageViewer image = new ImageViewer(imageName);
      splashWindow.add("North", image);
   } /* endif */

   if (!noticeText.equals("")) {
      TextArea text = new TextArea(noticeText);
      text.setEditable(false);
      splashWindow.add("Center", text);
   } /* endif */

   Button button = new Button("OK");
   button.addActionListener(this);
   splashWindow.add("South", button);

   splashWindow.pack();
   Dimension splashSize = splashWindow.getSize();
   Dimension screenSize = splashWindow.getToolkit().getScreenSize();

   if (splashSize.width>screenSize.width) {
      splashWindow.setSize(screenSize.width, splashSize.height);
      splashSize = splashWindow.getSize();
   } /* endif */

   if (splashSize.height>screenSize.height-30) { //allow for Start Bar/WarpCenter
      splashWindow.setSize(splashSize.width, screenSize.height-30);
      splashSize = splashWindow.getSize();
   } /* endif */

   splashWindow.setLocation((screenSize.width-splashSize.width)/2,
			    (screenSize.height-30-splashSize.height)/2);

   parentFrame.setEnabled(false); //workaround for modality deadlock
   splashWindow.setVisible(true);

Furthermore, enter the following code, which causes the splash dialog to be dismissed when the button press occurs, in the actionPerformed method:

   splashWindow.setVisible(false);
   splashWindow.dispose();
   parentFrame.setEnabled(true); //workaround for modality deadlock
   parentFrame = null;

There are also a few other miscellaneous lines to add, which are clearly marked in the SplashScreenDip.java and SplashScreenDipCustomizer.java source files from C:\Extender\src\com\ibm\beans\samples\dips\splash.

And with that, were done! We have a working dip, simply by filling out a few notebook pages and adding a few lines of code. Congratulations on generating your first dip!

Conclusion

This walk-through has shown that with the help of the wizard, a useful dip can be generated in just a few minutes. For an example of a more complex dip, there is also the Performance Dip (and an accompanying perform.wiz model file), which emits a very different (and much longer) dip source file. The files generated by the Dip Creation Wizard are heavily commented and meant for human inspection, as a teaching tool for understanding the issues involved in dip development. You will find that the Dip Creation Wizard takes care of most of the tedious, boiler-plate code common to most dips, freeing the developer to concentrate on the logic that actually makes the dip unique and useful. Good luck, and happy dip creation!


[ Top of Page | Previous Page | Table of Contents | Documentation Homepage ]