Following is a very quick example on how to get Hitch working quickly on a form. The following form needs to be able to pass the data it collects into the Person object.

Simple form example.

package com.silvermindsoftware.hitch.example;

import javax.swing.*;
import java.awt.*;

public class PersonFormPanel extends JPanel {

    private Person person;

    private JTextField 
        firstName, middleName, 
        lastName, age;
    private JComboBox sex;
    private JFormattedTextField birthDate;
    private JTextArea notes;

    public PersonFormPanel() {
        //Layout and initialization of components removed for brevity
    }
}

The Person object is a simple bean that consists of fields and getters/setters. Take note that the fields have the same name as the component fields in the form. This is a convention that can be used to cut down on the amount of manual binding configuration you would need to do. When the fields and components are identically named auto binding is able to determine which components to bind without manual configuration.

Person object

package com.silvermindsoftware.hitch.example;

public class Person {

    private String firstName;
    private String middleName; 
    private String age; 
    private String sex; 
    private Date birthDate;
    private String notes;

    // getters and setters ommitted for brevity

}

In our form we need to add a binder as an instance variable on the form. You can add this anywhere that an instance variable can be defined. In this example we define it at the very top of our form class. When the binder initializes it parses the class looking for any configuration information it needs in order to bind between the model and form.

Add Binder

    // setup a final binder instance variable
    private final Binder binder = BinderManager.getBinder(this);

package com.silvermindsoftware.hitch.example;

import javax.swing.*;
import java.awt.*;

public class PersonFormPanel extends JPanel {

    // setup a final binder instance variable
    private final Binder binder = BinderManager.getBinder(this);

    private Person person;

    private JTextField 
        firstName, middleName, 
        lastName, age;
    private JComboBox sex;
    private JFormattedTextField birthDate;
    private JTextArea notes;

    public PersonFormPanel() {
        //Layout and initialization of components removed for brevity
    }
}

Set @Form annotation that tells the binder to autoBind objects defined with @ModelObject annotaions. When the binder parses the class for annotations it will automatically determine which components and model properties should be bound.

Add @Form Annotation.

...
@Form( autoBind = true )
public class PersonFormPanel extends JPanel {
...

package com.silvermindsoftware.hitch.example;

import javax.swing.*;
import java.awt.*;

@Form( autoBind = true )
public class PersonFormPanel extends JPanel {

    // setup a final binder instance variable
    private final Binder binder = BinderManager.getBinder(this);

    private Person person;

    private JTextField 
        firstName, middleName, 
        lastName, age;
    private JComboBox sex;
    private JFormattedTextField birthDate;
    private JTextArea notes;

    public PersonFormPanel() {
        //Layout and initialization of components removed for brevity
    }
}

Define the default model object using the ModelObject annotation. The default model object must be explicitly defined with the isDefault = true. The importance of the isDefault attribute will be explained later in this document.

Add @ModelObject annotation defining default Model Object

...
    @ModelObject (isDefault = true)
    private Person person;
...

package com.silvermindsoftware.hitch.example;

import javax.swing.*;
import java.awt.*;

@Form( autoBind = true )
public class PersonFormPanel extends JPanel {

    // setup a final binder instance variable
    private final Binder binder = BinderManager.getBinder(this);
    
    @ModelObject (isDefault = true)
    private Person person;

    private JTextField 
        firstName, middleName, 
        lastName, age;
    private JComboBox sex;
    private JFormattedTextField birthDate;
    private JTextArea notes;

    public PersonFormPanel() {
        //Layout and initialization of components removed for brevity
    }
}

Finally we will add the code that copies data between the form and the model. We'll add a button called save that calls Binder.updateModel(...) and we'll add the Binder.populateForm(...) to the constructor to retrieve the initial person values from the model object.

Make binder calls

...
    public PersonAnnotationFormPanel() {
        initComponents();
        binder.populateForm(this);
    }
...
    private void update() {
        binder.updateModel(this);
        System.out.println(person.toString());
    }
...

package com.silvermindsoftware.hitch.example;

import javax.swing.*;
import java.awt.*;

@Form( autoBind = true )
public class PersonFormPanel extends JPanel {

    // setup a final binder instance variable
    private final Binder binder = BinderManager.getBinder(this);
    
    @ModelObject (isDefault = true)
    private Person person;

    private JTextField 
        firstName, middleName, 
        lastName, age;
    private JComboBox sex;
    private JFormattedTextField birthDate;
    private JTextArea notes;

    private JButton submit;

    public PersonFormPanel() {
        initComponents();
        binder.populateForm(this);
    }

    private void initComponents() {

        //Layout and initialization of components removed for brevity
        JButton submit = new JButton("Submit");
        submit.addActionListener(new ActionListener() {
            public void actionPerformed(ActionEvent e) {
                update();
            }
        });
    }

    private void update() {
        binder.updateModel(this);
        System.out.println(person.toString());
    }
}

That is all there is to the basics of Hitch. Each time you use hitch the above process will most likely be a regular part of how you start.