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:
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.
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.
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.
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);
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
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!"}
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.