3 Modifying ADF Swing Forms and Panels

This chapter describes how to customize an ADF Swing application using the Java visual editor. You use the Data Controls panel to insert databound UI components into an ADF Swing-prepared form or panel.

This chapter includes the following sections:

Section 3.1, "About Modifying ADF Swing Forms and Panels"
Section 3.2, "How to Assemble ADF Swing Forms Using the Java Visual Editor"
Section 3.3, "How to Insert UI Components into ADF Swing Panels"
Section 3.4, "How to Change Client Data Model References"
Section 3.5, "How to Open an ADF Swing Form with an Action Handler"
Section 3.6, "How to Drop Data Panels Onto an Empty ADF Swing Form"
Section 3.7, "How to Lay Out Data Panels in an Empty Swing Form"
Section 3.8, "Binding a Method with Parameters in an ADF Swing Form"

3.1 About Modifying ADF Swing Forms and Panels

After you generate ADF Swing forms and panels using the ADF Swing wizards, you may want to customize the generated application files. JDeveloper helps you customize the application using the visual tools. For example, you can use the Data Controls panel to insert already databound UI components into an ADF Swing-prepared form or panel.

3.1.1 Value Bindings for the Entire Collection or Data Object

The Data Controls panel provides UI components that you can use to bind an entire data collection (which consists of data objects that comprise a row set), as shown in the Table 3-1.

Table 3-1 UI Components That Can Be Bound to an Entire Data Collection

UI Component	Drag and Drop As	ADF Binding Type
	Table	Table binding
	Combo Box	List binding in Navigation mode
	List (inside a ScrollPane)	List binding in Navigation mode
	Spinner	List binding in Navigation mode
	Radio Button Group	List binding in Navigation mode
	NavigationBar	Iterator binding
	Tree	Tree binding
	Graph	Graph binding
	Slider	Scroll binding
	ScrollBar	Scroll binding

3.1.2 Value Bindings for Individual Data Object Attribute Values

The Data Controls panel provides UI components that you can use to bind a single data object attribute, as shown in Table 3-2.

Table 3-2 UI Components That Can Be Bound to a Single Data Object Attribute

UI Component	Drag and Drop As	ADF Binding Type
	TextField	Attribute binding
	Edit Pane	Attribute binding
	JULabel	Attribute binding
	Label For (for ADF Business Components to display attribute's label control hint)	Attribute binding
	Password Field	Attribute binding
	Text Area	Attribute binding
	Text Pane	Attribute binding
	Button LOV	LOV binding
	Check Box	Boolean binding
	Formatted Edit Field	Formatted Text binding
	Combo Box	List binding in Enumeration mode
	List	List binding in Enumeration mode
	Spinner	List binding in Enumeration mode
	Radio Button Group	List binding in Enumeration mode
	Progress Bar	Bounded Range binding
	Scroll Bar	Bounded Range binding
	Slider	Bounded Range binding

3.2 How to Assemble ADF Swing Forms Using the Java Visual Editor

The Create ADF Swing Empty Form dialog lets you create an empty form that you can use to assemble an ADF Swing form without the need to write additional Java code. The main() defined in the ADF Swing empty form contains ADF Swing code, known as bootstrap code, that:

Establishes a connection to a business service instance, such as an ADF Business Components application module, that provides the data model for the form.
Creates an instance of a panel binding from the data model to provide data access to the databound Swing components.

The bootstrap code generated by the wizard permits the ADF Swing empty form to share its panel binding with ADF Swing data panels that you add. You can use the Java visual editor to add the ADF Swing data panels to assemble the final databound ADF Swing form.

Note:

The Create ADF Swing Form wizard helps you generate databound ADF Swing forms to browse and edit ADF Business Components view objects that you select during the process of using the wizard. If you need to create an ADF Swing form of your own design, start with an empty form that is initially databound.

To create a databound ADF Swing form entirely within the Java visual editor:

Create an empty form using the Create ADF Swing Empty Form dialog. This adds an ADF Swing frame to your user interface project that can share a panel binding.

For more information, see Section 2.9, "How to Create an Empty ADF Swing Form."
Drop an ADF Swing data panel onto the ADF Swing empty form.

For more information, see Section 3.6, "How to Drop Data Panels Onto an Empty ADF Swing Form."

3.3 How to Insert UI Components into ADF Swing Panels

Use the Data Controls panel to insert databound controls into an ADF Swing panel.

Note:

The Data Controls panel may appear empty when you first open it. Compile the data model project to populate the panel with data objects.

Before you begin:

You will need to complete these tasks:

Create a data model project for your business components.

In order to use business components with your ADF Swing forms, you must first create a project with an ADF Business Components application module.
Compile the data model project.

When your data model project uses ADF Business Components as its business service, JDeveloper registers the business service as an ADF data control for you.

To insert a databound UI component into the panel in the Java visual editor:

Create an empty ADF Swing form or panel using the wizards.

For more information, see Section 2.1.1, "ADF Swing Design Time Wizards."
Open the form in the Java visual editor and click the Design tab.
In the Applications window, click the expand icon in the Data Controls header.
In the Data Controls panel, drag the data collection, attribute, or action that you want to bind to a UI component into the open document.
From the Add Child popup list, select the UI component that you want to add to the open document.

The new UI component appears in the document you are editing.

After you lay out the data panel or form, you may improve the performance of your ADF Swing application by defining the fetchAttributeProperties() method in your form. This ensures your form performs in batch mode to fetch attribute values.

3.4 How to Change Client Data Model References

You do not need to edit your application code to change the data model definition it will use to connect to your business services data source. The definition is contained entirely in the metadata for the user interface project in two files: DataBindings.cpx and PageDef.xml.

You might want to do this because you had been using a local configuration to test your application in JDeveloper and you now want to change to a data model definition that uses a remote deployment configuration. You could also decide to use an entirely different data model defined in a different business service project. Again, no code changes are required to accomplish this task.

To reference the new client data model definition in the ADF Swing metadata:

Add a new client data model definition to the DataBindings.cpx file in your user interface project and remember the name you chose (for example, remotedatamodel).

For more information, see Section 2.6, "How to Create a Client Data Model Definition."

Note:

If you change your data model to use an ADF Business Components application module from a package in a different project and the new application module is defined as Session Bean (BMT), then you must modify the <ejb-ref> entry in the web.xml file, as well as update the.cpx file.
Optionally, you can open the DataBindings.cpx file in the XML editor and edit the attributes of the BC4JDataControl definition:
- Choose Window > Structure to display the Structure window for the file.
- In the Structure window, select the data control node you want to modify.
- Choose Window > Properties to display the data control definition and edit its attributes.
Open the PageDef.xml file in the XML editor, click the Overview tab and select any binding that references the old data control.
In the Properties window, expand the Common section and select the Data Source for the desired collection from the dropdown list. You can then select the desired Attribute for the selected data source from the dropdown list.

Repeat for each binding in the binding definition.

3.5 How to Open an ADF Swing Form with an Action Handler

You can use the ADF Swing wizards to create ADF Swing forms with various databound controls. Later, when you want your ADF Swing forms to run from a single main window, you can create an ADF Swing frame that contains:

The bootstrap code to create the business service client data model connection
An action event handler to open the ADF Swing form and pass it a panel binding

When the user performs an action in the UI, such as clicking a button, an event is issued. Events are objects that describe what happened and are only reported to registered listeners. JDeveloper generates all of this code for you. The following procedure describes the code you must supply to open an ADF Swing form when the button is clicked.

To define an action to open an ADF Swing form:

Create a empty ADF Swing frame that creates a connection to the business service for the form.

For more information, see Section 2.9, "How to Create an Empty ADF Swing Form."
Open the empty ADF Swing frame in the Java visual editor and delete the Navigation Bar and Status Bar generated by the Create ADF Swing Empty Form dialog.
Add a JButton control from the Components window to the data panel of the empty form.

For more information, see Section 3.3, "How to Insert UI Components into ADF Swing Panels."
Select the button in the Java visual editor.
In the Properties window, expand the Events section and in the actionPerformed field enter the name of the function you want executed whenever the button is clicked and press the Enter key.

JDeveloper takes you to a stub of your function in the source editor.
Add code to the event stub to create the ADF Swing form you want to display and set its visible property to true:

FrameMyNewView frame = new FrameMyNewView(getPanelBinding());frame.setVisible(true);

The getPanelBinding() method allows you to share the panel binding from main ADF Swing frame. This results in the iterator bindings to be shared between ADF Swing forms. The new frame will automatically be synchronized with the navigation bar and status bar in the first detail of the master-detail frames.

Or

Add code to create the ADF Swing form and set a new panel binding when you don't want the form to be synchronized with the frame that opened it:

FrameMyNewView(new JUPanelBinding(getPanelBinding().getApplicationName(),null));frame.setVisible(true);

3.6 How to Drop Data Panels Onto an Empty ADF Swing Form

You can assemble an ADF Swing form using existing data panels from your current project or you can insert a new empty data panel which you can lay out with specific controls.

To add a data panel to an ADF Swing Empty Form:

Open the empty form in Java visual editor and click the Design tab.
Choose Window > Components to display the list of Swing controls.
In the Components window, select ADF Swing Regions to view the existing data panels in your project.
Drag the ADF Swing panel you want to reuse onto the empty panel.
In the Select Controls dialog, select how you want the form to handle data panel.
Add controls to the data panel.

For more information, see Section 3.3, "How to Insert UI Components into ADF Swing Panels."

The ADF Swing panel that you add to an ADF Swing form receives its databinding from the ADF binding container. When setBindingContext() is called on the form, the binding container for the form is created together with the panel's binding container.

3.7 How to Lay Out Data Panels in an Empty Swing Form

You can lay out any Swing panel using the FormLayout layout manager provided with the JGoodies Form framework. The FormLayout gives you excellent grid-based control over the placement and alignment of controls. Unlike other layouts, you can fill components across grid cells.

To set FormLayout on an ADF data panel:

Open the form in the Java visual editor and click the Design tab.
Choose Window > Properties.
In the Property window, expand the Visual section and select FormLayout from the layout dropdown list.

For more information, see "Adding Components" in Developing Applications with Oracle JDeveloper.
Customize the panel layout.

For more information, see "Working with Layout Managers" in Developing Applications with Oracle JDeveloper.

3.8 Binding a Method with Parameters in an ADF Swing Form

You can use the Data Controls panel to insert a button that will allow the user to initiate an action defined by a method of your business service. If your business service is ADF Business Components, many standard actions are predefined (such as Create, Delete, Next, Previous, Commit, and Rollback).

3.8.1 How to Populate the Data Controls Panel with JavaBean Methods

When your business service is a JavaBean class, you must define a public method and register the bean as an ADF data control. The method that you create may define arguments whose values can be supplied by the ADF Swing form user.

Alternatively, you can supply the parameter values of the method in the Properties window.

To populate the Data Controls panel with your JavaBean methods:

Define the JavaBean that you want your Oracle ADF application to access.

The business services appear in your data model project
Register the business services in your data model project with the ADF data controls.

When your data model project uses ADF Business Components as its business service, JDeveloper registers the data control for you.

3.8.2 How to Create an ADF Swing Form with Method Bindings

When you can create an ADF Swing form, you have the option of displaying a method binding as a Button or Method panel. The Method panel displays a component for each parameter and a component that display each method result.

To create an ADF Swing Form with method bindings:

Open the data panel in the Java visual editor.
In the Data Controls panel, expand the Operations folder for the data collection or data control that displays the desired custom method.

The Data Controls panel hierarchy represents operations (such as Create and Delete) that apply to a specific data collection in the Operations folder below the data collection. When supported by the ADF data control for your business service, you can also select operations (such as Commit and Rollback) that apply to all data collections in the current document's binding context in the Operations folder at the top branch of the hierarchy.
Drag the desired operation into the open document.

A method with no parameters or result is automatically added as a JButton component to initiate the action. If the method has parameters or a return value, JDeveloper displays a popup that lets you select how you want to add the method. Select one of these options depending on how you want the form to display the method binding in your application.
- Select Button when you want to add a button that will initiate the action. You are responsible for passing parameters to the method.
- Select Method when you want to add a method panel that will display a component for each parameter and a component to display a method result, as needed. In the Select Controls for Parameters and Results dialog that displays, select the components the panel will display.
JDeveloper adds code to the class file to bind the JButton or JPanel to the operation.
If you drop the method as a Button, and you want to supply parameter values yourself, you can add a text field to the form and add a focusListener to the text field and modify its focusLost() method in the data panel's.java file, using the code in Example 3-1 to pass the parameter to the method:
Example 3-1 Code for Passing a Parameter to Method
```
private void jTextField1_focusLost(FocusEvent e)   {
   JUCtrlActionBinding action = 
        (JUCtrlActionBinding)panelBinding.getCtrlBinding(jButton1);
   ArrayList arg1 = new ArrayList();
   arg1.add(jTextField1.getText());
   action.setParams(arg1);
}
```
Repeat this step to create an event handler for each text field that supplies a method parameter.

3.8.3 What You May Need to Know About Displaying a Method Result Using a JTable Component

When you drop a custom method with a return value from the Data Controls panel, JDeveloper prompts you for the component to bind to the method result. Note that if you choose to display a result that is a collection in a JTable, your application may fail at runtime with a NullPointerException when the Swing JTable component attempts to prepare the renderer. This exception is due to a Swing JTable limitation that prevents it from setting up renderers for the Integer type (Swing supports Numbers, Doubles, Floats, Dates, and Booleans). You will need to subclass the JTable and set a default renderer for types that Swing does not natively support.

For example, to install a custom renderer for Integer, you can use the code shown in Example 3-2.

Example 3-2 Installing a Custom Renderer for Integer

private JTable jTable1 = new JTable() {
   protected void createDefaultRenderers() {
     super.createDefaultRenderers();
     setDefaultRenderer(Integer.TYPE,
   super.getDefaultRenderer(java.lang.Number.class));
   }
}