View source for Scout/HowTo/3.7/Add a custom GUI component

{{ScoutPage|cat=HowTo}}

=Extending Scout (under construction)=

If the controls provided by Scout don’t fit your needs, you can easily create custom controls. This section describes how this can be done.

To create new controls it is important to understand how scout displays a control. Remember we have the client plugin where you can define the form and the controls on it, let’s call them scout controls. Additionally we have the gui plugin which creates the effective SWT respectively Swing-Controls based on the code in the client plugin. But how does the gui plugin know which client controls belong to which gui controls? This mapping is done by an extension point.

As an example we will create an AbstractDrawLineField. In this field a user can draw a line from a start point to an end point.

==CREATING THE SCOUT CONTROL==
Every scout control on a form extends from AbstractFormField. So what you have to do is to create a new class which extends from AbstractFormField. Instead of directly extend from AbstractFormField you could use AbstractCustomField as super class which is actually the recommended way to go. AbstractCustomField does not provide any additional logic but since it implements the Interface ICustomField it is easier to distinguish between controls provided by the framework and controls provided by you. Additionally to the main class it is recommended to create an interface for your control.
For our AbstractDrawLineField, we create a new package com.bsiag.minicrm.client.ui.form.fields.ext in the client plugin. In this package we create an interface IDrawLineField and IDrawLineUiFacade. IDrawLineField extends the interface IFormField. Then we create the class AbstractDrawLineField which extends AbstractCustomField and implements IDrawLineField.
===Properties===
Now you have to think about what your field should provide. A common scout field normally consists of some properties and some execXY methods. Please notice that every form field is also an IPropertyObserver. So if you think that someone else could be interested in your property, then you should make use of the protected field m_propertySupport. This is especially necessary if the property defines behaviour of the gui control. If someone dynamically changes the property on your field the gui control has to be informed about it otherwise it would not be reflected on the gui.
The AbstractDrawLineField has two properties, the start and the end point. Thus we add now the following code to the IDrawLineField interface:

<pre>
public static final String PROP_START = "startPoint";
public static final String PROP_END = "endPoint";

Point getStart();
void setStart(Point p);

Point getEnd();
void setEnd(Point p);

IDrawLineUiFacade getUiFacade();
</pre>
This interface is now already finished. The getUiFacade method will be needed to receive events from the gui control. In the AbstractDrawLineField, we implement now these methods with the usage of m_propertySupport:
<pre>
  private IDrawLineUiFacade m_uiFacade;

  @Override
  public Point getEnd() {
    return (Point) propertySupport.getProperty(PROP_END);
  }

  @Override
  public void setEnd(Point p) {
    propertySupport.setProperty(PROP_END, p);
  }

  @Override
  public Point getStart() {
    return (Point) propertySupport.getProperty(PROP_START);
  }

  @Override
  public void setStart(Point p) {
    propertySupport.setProperty(PROP_START, p);
  }

  @Override
  public IDrawLineUiFacade getUiFacade() {
    return m_uiFacade;
  }
</pre>

===Default Values===
Another important thing about properties is the way they are initialized. For each property there should be a getConfiguredPropertyName-function. With this method the user is able to set the initial value of the property. This initial value is read in the method initConfig(). This means for your custom field that it has to override the method initConfig() too and has to fill up the actual properties with the initial values of the getConfigured functions.
For the AbstractDrawLineField we need four getConfigured methods, two for each point. The annotations are needed for the Scout SDK only.
<pre>
@ConfigProperty(ConfigProperty.INTEGER)
@Order(500)
@ConfigPropertyValue("0")
protected int getConfiguredStartX(){
  return 0;
}

@ConfigProperty(ConfigProperty.INTEGER)
@Order(510)
@ConfigPropertyValue("0")
protected int getConfiguredStartY(){
  return 0;
}

@ConfigProperty(ConfigProperty.INTEGER)
@Order(520)
@ConfigPropertyValue("0")
protected int getConfiguredEndX(){
  return 0;
}

@ConfigProperty(ConfigProperty.INTEGER)
@Order(530)
@ConfigPropertyValue("0")
protected int getConfiguredEndY(){
  return 0;
}

@Override
protected void initConfig(){
  super.initConfig();
  setStart(new Point(getConfiguredStartX(), getConfiguredStartY()));
  setEnd(new Point(getConfiguredEndX(), getConfiguredEndY()));
}
</pre>
===Receiving GUI Events===
Now we have to think about which gui events we want to propagate to the scout control. These events are handled by uiFacade.
In our example, we have two important events. Setting a new start and setting a new end point. Add to the façade interface these two methods:
void setStartFromUI(Point p);
void setEndFromUI(Point p);
Now add this inner Class to AbstractDrawLineField:
<pre>
private class P_UiFacade implements IDrawLineUiFacade{
  public void setEndFromUI(Point p){
    setEnd(p);
  }

  public void setStartFromUI(Point p){
    setStart(p);
  }
}
</pre>
And add this line of code as the first statement in the initConfig method:
m_uiFacade  = new P_UiFacade();
==CREATING THE GUI CONTROL==
After creating the custom field, the corresponding gui control has to be created. Every swt gui control extends from SwtScoutFieldComposite (SWT) or from SwingScoutFieldComposite (Swing).
We create for our AbstractDrawLineField a swing implementation. Create a new package com.bsiag.minicrm.ui.swing.form.fields.ext in the ui.swing plugin. Create in this package a new class SwingScoutDrawLineField that extends SwingScoutFieldComposite.
===Implementation===
Some important methods in a gui field are initializeSwt / initializeSwing, attachScout and handleScoutPropertyChange. The actual gui composite is created in the initializeSwt / initializeSwing method. Properties of the scout field are normally handled in the method attachScout respectively in the method handleScoutPropertyChange.
To fire events which should be handled in the scout control and which normally leads to an execution of an execXY method the UIFacade of a scout field should be used.
For the SwingScoutDrawLineField we have a mouse listener that propagates the point changes from the gui to the scout control. When then the scout control adjusts the point properties, these changes are handled in the handleScoutPropertyChange method and there the line in the gui will be updated. Paste the following code in the SwingScoutDrawLineField class:
<pre>
private P_MouseListener m_mouseListener;

@Override
protected void initializeSwing(){
  m_mouseListener = new P_MouseListener();
  JPanelEx container=new JPanelEx(new BorderLayoutEx());
  container.setOpaque(false);
  JStatusLabelEx label=new JStatusLabelEx();
  container.add(label,BorderLayoutEx.CENTER);

  MyComponent field = new MyComponent();
  SwingUtility.installDefaultFocusHandling(field);
  container.add(field);

  field.addMouseMotionListener(m_mouseListener);
  field.addMouseListener(m_mouseListener);

  setSwingContainer(container);
  setSwingLabel(label);
  setSwingField(field);
  //layout
  getSwingContainer().setLayout(new LogicalGridLayout(getSwingEnvironment(),1, 0));
}

@Override
protected void attachScout(){
super.attachScout();
  updateLineFromScout();
}

protected void updateLineFromScout(){
  getSwingField().repaint();
}

protected void handleSwingStartPointChanged(final Point location){
  RunnableWithData t=new RunnableWithData(){
    @Override
    public void run(){
      getScoutObject().getUiFacade().setEndFromUI(location);
      getScoutObject().getUiFacade().setStartFromUI(location);
    }
  };
  getSwingEnvironment().invokeScoutLater(t, 2345);
}

protected void handleSwingEndPointChanged(final Point location){
  RunnableWithData t=new RunnableWithData(){
    @Override
    public void run(){
      getScoutObject().getUiFacade().setEndFromUI(location);
    }
  };
  getSwingEnvironment().invokeScoutLater(t, 2345);
}

@Override
protected void handleScoutPropertyChange(String name, Object newValue){
  if(name.equals(IDrawLineField.PROP_START) || name.equals(IDrawLineField.PROP_END)){
    updateLineFromScout();
  }
  super.handleScoutPropertyChange(name, newValue);
}

private class MyComponent extends JComponent{
  private static final long serialVersionUID=1L;

  @Override
  public void paint(Graphics g){
    super.paint(g);
    g.setColor(getBackground());
    g.fillRect(0, 0, getWidth(), getHeight());
    g.setColor(getForeground());
    if(getScoutObject().getStart() != null && getScoutObject().getEnd() != null){
      g.drawLine(getScoutObject().getStart().x, getScoutObject().getStart().y, getScoutObject().getEnd().x, getScoutObject().getEnd().y);
    }
  }
}

private class P_MouseListener extends MouseAdapter{
  private boolean m_mouseDown = false;
  @Override
  public void mousePressed(MouseEvent e){
    m_mouseDown = true;
    handleSwingStartPointChanged(e.getPoint());
  }
  @Override
  public void mouseReleased(MouseEvent e){
    m_mouseDown = false;
    handleSwingEndPointChanged(e.getPoint());
  }
  @Override
  public void mouseDragged(MouseEvent e){
    if(m_mouseDown){
      handleSwingEndPointChanged(e.getPoint());
    }
  }
}
</pre>

==MAP THE CONTROLS==
To tell the gui plugin which control belongs to which gui control an extension has to be add in the gui plugin. For a SWT gui field we need the extension point org.eclipse.scout.rt.ui.swt.formfields and for a Swing we use org.eclipse.scout.rt.ui.swing.formfields. In this extension point we have to specify which model class maps to which ui class. As model class we use usually the interface and not the concrete class.
For our example, open the plugin.xml from the ui.swing plugin. Go to the Extensions tab on the bottom of the manifest editor and click Add…. Uncheck the checkbox at the bottom and select the org.eclipse.scout.rt.ui.swing.formfields extension point before you click Finish. Right-click the newly created extension in your manifest editor and select New > formField.
Now enter in the name text box “Draw Line Field” and select as modelClass “com.bsiag.minicrm.client.ui.form.fields.ext.IDrawLineField”. Now we have to specify the ui class. Right-click on the formField extension and select New > uiClass. There we select the class “com.bsiag.minicrm.ui.swing.form.fields.ext.SwingScoutDrawLineField”.
==TEST THE DRAWLINEFIELD==
You can now create a new Form where you use the DrawLineField. If you set the grid height to about a value of eight and disable the label you get a big field. Of course you need to start the Swing client and not the SWT client.