Current Page: NeXtMidas User's Guide Graphics Creating Custom Widgets
| #### 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 the Class Configuring the setupBean() Method Adding the Control to the GWidget Panel Building the Custom Control Calling the Custom Control Closing Notes #### 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.