Previous Next        Current Page: NeXtMidas User's Guide / Graphics / Creating Custom Widgets
back

The BEAN Control Widget

Since NeXtMidas 2.9.1, a user may develop their own custom widget controls and call them as they would a regular macro GCONTROL widget by using BEAN. The documentation below provides an overview on creating a custom control using the BEAN widget.

We will use the simple GSwingLabel custom control to demonstrate the creation and use of custom BEAN widgets. GSwingLabel is a simple control that creates a pure-Swing JLabel and adds it to the user's NeXtMidas context. To see the entire source code for GSwingLabel, please see the nxm.ucl.libg.GSwingLabel class located in your NeXtMidas distrubtion.

The following subsections provide an overview of creating a custom control:

Creating Your Class

The custom control's class should be added to the UCL/libg folder or your own option tree. The class must extend GWidget, must include an empty constructor and should implement the BeanWidget interface if the control will use Swing-based components. As of NeXtMidas 2.9.1, the BeanWidget interface requires any implementing class to define the functionality for the setupBean() method. Technically, GWidget also implements the setupBean() method, but your custom control will likely require custom code within setupBean(). In addition, the class must contain an empty constructor. Both the empty constructor and the setupBean() method are required in order for your custom control to invoked correctly. See the "Class Stub Example" below for an example class stub that meets the above requirements.

Class Stub Example
package nxm.ucl.libg;

import nxm.sys.inc.MessageHandler;
import nxm.sys.libg.BeanWidget;
import nxm.sys.libg.GWidget;

/**
  A simple class to create a Swing-based JLabel from the GCONTROL BEAN widget.
  This class will be expanded upon as new examples or techniques are added
  to the NeXtMidas User's Guide.
  @author NeXtMidas Developer
  @version $Id: BeanWidgets.html,v 1.3 2011/03/09 16:22:56 jwb Exp $
  @since NeXtMidas 2.9.1
 */
public class GSwingLabel extends GWidget implements BeanWidget {

  private MessageHandler mh;

  private String labelText = "";

  protected JLabel swingLabel;

  /**
    Empty constructor.  Required!
   */
  public GSwingLabel () {}

   /**
    Called by GCONTROL to "create" this BEAN-based widget.
    @param name The name of the widget/control.
    @param parent The parent widget/control.
    @param title The Midas title of the widget/control.
    @param flags Any applicable flags passed into the widget/control.
    @param mh The MessageHandler reference for sending processMessages.
    @param argTable The table of Midas arguments sent into this widget/control.
   */
  public void setupBean(String name, Object parent, String title,
    int flags, MessageHandler mh, nxm.sys.lib.Table argTable) {

    // Must call GWidget.setupBean. Required!
    super.setupBean(name, parent, title, flags, mh, argTable);

    // Define attributes of this class
    this.mh = mh;                   // Store a local reference to MessageHandler

    // Parse through the control arguments
    // We will add this functionality in the next step

    // Additional functionality
    // We will add this functionality in the next step

    // Add to the parent MWindow.  Required!
    addTo(parent);                  // calls GWidget's addTo method
  }
}

In the "Class Stub Example" above, you will notice that the setupBean() method is sent six arguments. Generally speaking, NeXtMidas will handle all of the parameters with the exception of argTable. The argTable argument contains the Table-based parameters specified in the call to create the control from the user's macro. Therefore, you may need to parse through the arguments table in order to gather any user-specified arguments for your control within the setupBean() See the example code below for a simple implementation of this process.

Configuring the setupBean() Method

public void setupBean (String name, Object parent, String title,
    int flags, MessageHandler mh, nxm.sys.lib.Table argTable) {

    // Must call GWidget.setupBean
    super.setupBean(name, parent, title, flags, mh, argTable);

    // Define attributes of this class
    this.mh = mh;                 // Store a local reference to MessageHandler

    // Parse through the control arguments
    if (argTable != null) {

      // Argument "P1" is already used for the class name
      if (argTable.size() > 0)
        labelText = argTable.getS("LABELTEXT");

      // Additional functionality
      if (labelText != null) {
        open(labelText);            // user should define this open() method
      }

    // Add to the parent MWindow.  Required!
    addTo(parent);                // calls GWidget's addTo method
  }

At this point, the functionality required for the class to function as a custom BEAN widget is complete. The rest of the widget implementation will be similar to other controls located in UCL/libg and SYS/libg.

Adding the Control to the GWidget Panel

Note that at some point your control, panel, or combination of the two, must be added to the GWidget panel. In our example, the line below is added to the bottom of the open() method.. 

// Add the JLabel to the NeXtMidas panel
panel.add(swingLabel);

Building the Custom Control

To build your custom control, issue the bld <className> <area> <option tree> from the NeXtMidas shell. With the GSwingLabel example, the class is contained in the nxm.ucl.libg package. 

bld GSwingLabel libg ucl

Calling the Custom Control

Next, the user will need to create a user macro in order to test their newly compiled custom control. In the macro, the new control is added by using the GCONTROL BEAN control, followed by <P1=class path> and any optional parameters by using the TABLE={ARG1=VAL,ARG2=VAL,...}. In the example below, we will add the sample GSwingLabel control to our macro with a label value of 'Hello, World!'. 

GCONTROL BEAN mySwingLabel "mySwingLabel" P1=nxm.ucl.libg.GSwingLabel TABLE={LABELTEXT="HELLO,WORLD!"}

Closing Notes

The GSwingLabel control is a very simple example of how a user may create a simple widget control. For more extensive examples of using the BEAN widget to create complicated control widgets, please see the nxm.ucl.libg.GDatePicker class.


back