Code documentation
Development Tools
Code Structure
Techniques and Standards
Help and Web Site
How To
Functional Info
Background Info

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI.org

JMRI Code: Using the NetBeans Swing GUI Builder

Portions of the JMRI Graphical User Interface (GUI) code are maintained using the NetBeans Swing GUI Builder (the "Builder"). This page is a guide to using the Builder tool. See Building with NetBeans for a general introduction to using NetBeans for maintaining JMRI.

Introduction

NetBeans 7.4 or 8.0 includes a Swing GUI Builder that makes it easier to maintain a Java Swing-based GUI (such as JMRI) than writing the user interface entirely by hand.

This tool can create code that is not ideally separated into human-maintained and generated Java code. If you use NetBeans, you are protected from this, as the Builder does a good job of integrating its views with the source editor. However, if you use another editor, you will be exposed to this.

Using the Builder

The NetBeans IDE editor toolbar will automatically contain a button labeled Design if the Class being edited can also be edited in the Swing GUI Builder.

Clicking the Design button will present the ability to drag buttons, labels, panels, and other objects onto a window to visually place them. Any object that conforms to the JavaBean standard can be placed on the window and linked to other objects on the window, even if it does not have a visual representation.

Where the Builder cannot automatically generate code, it provides empty, or stub, methods that can be completed to implement the desired logic, and will automatically switch to the code view as needed.

Examining the Code

The Builder maintains two files: a .java file, containing compilable code, and a .form file, containing an XML representation of GUI along with code that is used to create the initComponents() method in the .java file.

.java File

In NetBeans, the code generated by the Builder, looks just like any other Java code, although portions of it cannot be edited (NetBeans simply does not allow the code to be changed). Stub methods will be editable, however, it will not be possible to change the method signatures (name, parameters, return values, or throws clauses).

A method, private void initComponents()

Other tools, however, will display the code very differently, and the code will contain the following non-standard, though valid, markings as comments that are hidden in NetBeans:

// <editor-fold defaultstate="collapsed" desc="Generated Code">
Hides everything between it and // </editor-fold> with the description Generated Code in NetBeans and other editors that recognize it. Code between these two comments can be viewed by clicking the + icon to the left of the description in those editors. It is used to hide code that should not be edited by hand.
// </editor-fold>
Used with // <editor-fold defaultstate="collapsed" desc="Generated Code">. See that comment's description for more information.
//GEN-BEGIN:<token>
Precedes a method or block of variables that is completely generated by the Builder. Such a method or block is followed by a corresponding //GEN-END:<token> comment.
//GEN-END:<token>
Follows a method or block of variables that is completely generated by the Builder. Such a method or block is preceded by a corresponding //GEN-BEGIN:<token> comment.
//GEN-FIRST:<token>
Precedes a method that generated code calls, but the body of which is written by a developer. Such a method is followed by a corresponding //GEN-LAST:<token> comment. The token is often event_<methodName>.
//GEN-LAST:<token>
Follows a method that generated code calls, but the body of which is written by a developer. This comment marks the closing curly brace in the method preceded by the corresponding //GEN-FIRST:<token> comment.

.form File

The .form file is completely hidden within the NetBeans IDE. Opening a .java file with a corresponding .form file (the same file name in the same package) will add the Design button to the editor tool bar, allowing the Builder to be used.

The .form file is an XML file adhering to the DTD in the NetBeans source code (linked to the head of the NetBeans trunk). NetBeans uses this file to store additional information outside the JavaBeans specification that is required to correctly generate the initComponents() method, stub methods, and variable lists. In the absence of other changes to the .java file, this file could be used to completely generate a new .java file, should that be necessary.

This file should not be edited by hand, but should be generated by the Builder.

See Also