This chapter describes how to use ADF Swing controls on ADF Swing forms and panels. In addition to the standard Swing controls that you can use to design ADF Swing applications, ADF Swing provides its own set of controls, called ADF Swing controls.
This chapter contains the following sections:
Section 7.4, "What You May Need to Know About Multimedia in ADF Swing Applications"
Section 7.9, "How to Use the JUNavigationBar Control with Find Mode"
Section 7.10, "How to Disable Find Mode for ADF Swing Controls in a Panel"
Section 7.11, "What You May Need to Know About Iterator Bindings in Find Mode"
Section 7.12, "How to Use the JURadioButtonGroupPanel Control"
In addition to the standard Swing controls that you can use to design ADF Swing applications, ADF Swing provides its own set of controls. These additional controls are available on the Data Controls panel:
JUArrayComboBox
JUImageControl
JULabel
JULabel - Label For
JULovEditButton
JUNavigationBar
JURadioButtonGroupPanel
JUShuttlePanel
JUStatusBar
The type of control binding used for a given ADF Swing control depends on the actions performed by the control. Table 7-1 identifies the bindings and the various ADF Swing controls that they support.
Table 7-1 Control Bindings and ADF Swing Controls
| Binding | ADF Swing Control |
|---|---|
|
Attribute binding |
Label For JULovEditButton (button for LOV dialog) JUImageControl JULabel |
|
Array Combobox binding |
JUArrayComboBox |
|
Iterator binding |
JUNavigationBar JUStatusBar |
|
List Binding in Enumeration Mode |
JUShuttlePanel |
|
List Binding in List of Values (LOV) Mode |
JURadioButtonGroupPanel |
Like the standard Swing controls that they supplement, these controls also rely on the MVC or Model-View-Controller architecture. The ADF Swing controls are unique because the controllers they rely on to manage end user interactions do not exist among the Swing controls. Together with the ADF model bindings, the ADF Swing controls allow you to design Java desktop applications with more diverse databound functionality.
The array combobox is an ADF Swing JUArrayComboBox control that can be bound to an attribute of a business service data collection that has been mapped as type oracle.jbo.domain.array. Because the array combobox displays its list of values from a single attribute, it works with the ADF attribute binding, which accesses the data stored in the database through an attribute of a data collection. Currently, without design-time support in JDeveloper for editing Object arrays, the elements of the array attribute are limited to Scalar values, such as numbers, strings, or date.
Note:
Although the JUArrayComboBox does not provide design-time support for using object arrays, you can create an extension inJDeveloper that implements the ADF Swing interface.
Users can use the array combobox to view the existing attribute values. They can also add, update, and delete displayed values.
To bind to an array attribute of type scalar:
In the user interface project, open the Java visual editor on the data panel or form.
In the Data Controls panel, drag the attribute you want to bind to the image control into the open form or panel.
From the Add Child popup list, select JUArrayComboBox.
JDeveloper adds code to the class file to bind the array combobox to the attribute:
myJUArrayComboBox1.setDocument((Document)panelBinding.
bindUIControl("MyAttribute", myJuArrayComboBox1"));
To insert a value to the array attribute:
In the Java visual editor, select the dropdown list and press Ctrl + Click to create a new empty list item.
In the empty list item, type the value and press Enter.
To update an existing value of the array attribute:
Select the item, type the new value and press Enter.
To remove an existing value from the array attribute:
Select the item and press Delete.
The image control is an ADF Swing JUImage control that can be bound to an attribute of a business service collection through the ADF Swing attribute binding. The attribute binding accesses images stored in the database through a particular data collection. Datatypes that the JUImage control supports includes images stored as:
ADF Business Components domain BLOB datatype
ADF Business Components domain Raw datatype
Oracle interMedia domain IMAGE type
To insert a databound image control into a form or panel:
In the user interface project, open the Java visual editor on the desired data panel or form.
In the Data Controls panel, drag the attribute you want to bind to the image control into the open form or panel.
From the Add Child popup list, select JUImageControl.
JDeveloper adds code to the class file to reference the MyImageAttribute binding definition in the page definition file associated with the form:
myJUImageControl1.setModel((JUDefaultControlBinding)
panelBinding.bindUIControl("MyImageAttribute",
myJUImageControl1));
To add a scrolling region to your image:
In the Properties window, set the autoscrolls field to True.
Within an ADF Swing form, users can delete and update the image file stored in the database, but they cannot edit the image itself.
The Image control consists of a panel with a display area and two buttons:
Change button to invoke an Open dialog box in which users can select the image file to load.
Clear button to delete the image.
To change the data binding of an image control in a form or panel:
Open the form or panel containing the JUImage control in the Java visual editor.
Right-click the JUImage control you want to change and select Edit Bindings from the menu.
The JUImage Control Binding dialog displays.
The JUImage ADF Swing control is available to access multimedia in the database. The JUImage control islimited to images only.
Note:
JDeveloper currently does not support audio and video usages of the OrdMediaControl component. This means that developers are not be able to create new applications using ADF Swing interMedia controls. However, the required interMedia libraries are still shipped withJDeveloper for backward compatibility. ADF Swing applications of previous JDeveloper releases that use interMedia will continue working when upgraded to ADF Swing.
The JUImage control is an earlier implementation of a control in ADF Swing used to display images from the database. Your application's performance is always improved when you can stream the image from the database's supported interMedia object types. In the case of the JUImage control, the image file must be entirely downloaded before the application can display it. Additionally, JUImage is limited to RAW, LONG RAW, BLOB, and interMedia IMAGE types.
The JULabel is an ADF Swing control that can be bound to an attribute of a business service collection through the ADF Swing attribute binding. The attribute binding accesses the data stored in the database through a particular data collection. The JULabel control renders the attribute value as a label.
Or, you can display the label from a control hint that has been defined for ADF Business Components attributes. For more information, see Section 7.6, "How to Use the Label For Control."
To insert a databound label into a form or panel:
Open the data panel in the Java visual editor.
For more information, see Section 2.10, "How to Create an Empty ADF Swing Panel."
From the Window menu, choose Applications.
In the Applications window, expand the Data Controls panel.
In the Data Controls panel, drag the attribute you want to bind to the label into the open form or panel.
From the Add Child popup list, select JULabel.
JDeveloper adds code to the class file to bind the JULabel to the attribute:
myJuLabel.setModel((JULabelBinding)panelBinding.bindUIControl("MyAttribute", myJuLabel));
Note:
The text property will be overwritten when you run the ADF Swing form.
To change the data binding of a label in a form or panel:
Open the form or panel containing the JULabel control in the Java visual editor.
Right-click the JULabel control you want to change and select Edit Bindings from the menu.
The Edit Attribute Binding dialog displays.
The Label For control is an ADF Swing JULabel control that can be bound to an attribute of a business service collection through the ADF Swing attribute binding. The binding accesses the previously defined control hint defined for an attribute of an ADF Business Components view object. The JULabel control renders the label from the defined hint.
Or, you can display the label from the attribute value. For more information, see to Section 7.5, "How to Use the JULabel Control."
To insert a databound label into a form or panel:
In the user interface project, open the Java visual editor on the data panel or form.
In the Data Controls panel, drag the attribute you want to bind to the Label For control into the open form or panel.
From the Add Child popup list, select Label For.
JDeveloper adds code to the class file to bind the JULabel to the attribute:
myjULabel1.setText(panelBinding.findCtrlValueBinding ("MyAttribute").getLabel());
Note:
The text property will be overwritten when you run the ADF Swing form.
To change the data binding of a label in a form or panel:
Open the form or panel containing the label control in the Java visual editor.
Right-click the JULabel control you want to change and select Edit Bindings from the menu.
The Edit Attribute Binding dialog displays.
The LOV edit button control is an ADF Swing JULovEditButton control that can be bound to an attribute of a business service collection through the ADF Swing attribute binding. The JULovEditButton control allows the user to make multiple selections for the displayed shuttle list.
To insert a databound LOV edit button into a form or panel:
In the user interface project, open the form or data panel in the Java visual editor.
In the Data Controls panel, drag the collection you want to bind to the JULovEditButton control into the open form or panel.
From the Add Child popup list, select Button LOV.
JDeveloper adds code to the class file to reference the DCShuttle binding definition in the page definition file associated with the form:
myjButton.setModel((ButtonModel)panelBinding.bindUIControl
("Address1",myjButton));
To change the data binding of an LOV edit button in a form or panel:
Open the form or panel containing the JULovEditButton control in the Java visual editor.
Right-click the JULovEditButton control you want to change and select Edit Bindings from the menu.
The Create Button LOV Binding dialog displays.
The navigation bar is an ADF Swing JUNavigationBar control that can be bound to:
A business service data collection through the model object
A JUPanel that has a panel binding passed to it through its constructor
The effect of these bindings determines the scope of the navigation bar actions. If you bind to a data collection, the JUNavigationBar lets you navigate on those controls that share the same panel and that are bound to the same data collection through its attributes. Whereas, you can control the navigation of controls in child panels, by adding the JUNavigationBar control to the containing panel and setting the panel binding.
In the user interface project, open the Java visual editor on the data panel or form.
In the Data Controls panel, drag the data collection you want to bind to the navigation bar control into the open form or panel.
From the Add Child popup list, select JUNavigationBar.
JDeveloper adds code to the class file to bind the JUNavigationBar to the collection:
jUNavigationBar1.setModel(JUNavigationBar.createViewBinding
(panelBinding, jUNavigationBar1, "MyDataCollection", null, "MyCollectionIterator"));
In the user interface project, open the Java visual editor on the layout panel that contains the panels you want to navigate on.
In the ADF Swing Controls page of the Components window, drag the JUNavigationBar control into the open form.
In the Properties window for the JUNavigationBar control, select the model field and select ADF Swing panel binding.
JDeveloper adds code to the class file to bind the JUNavigationBar to the panel binding passed into the current panel:
myNavBar.setModel(JUNavigationBar.createPanelBinding
(panelBinding, myNavBar));
In ADF Swing, you can support parameterized queries by using the JUNavigationBar control in an ADF Swing data panel with the Find mode enabled. Find mode lets users use the data panel to enter search criteria through supported ADF Swing control bindings.
When you run the panel, in Find mode, the navigation-mode component no longer forces the search criteria components to update. They will remain empty in order to permit the user to entry search criteria.
A typical usage for a data panel with Find mode is:
The user places the panel in Find mode.
For instance, a user may click the Find button, which is provided by default with a JUNavigationBar (that is bound to an ADF Business Components view object).
The user enters find criteria to restrict the results of the data already returned to the form.
The Find mode performs an anchored, wild card search.
It uses the first character of the search column as an anchor, where all the strings that begin with the entered string are matched.
Another control that you bind to the same view object in ADF Swing, such as the JTable control, displays the results of the parameterized query.
A parameterized query is a query that contains a placeholder that must be supplied at runtime. For example, in the following PL/SQL statement, min_salary is a placeholder for a parameter value that will be supplied at runtime.
SELECT ename, job, mgr FROM emp WHERE sal < :min_salary
The data panel in Find mode uses the ADF Swing control bindings to display fields for each attribute in the bound ADF Business Components view object whose queriable property is set to true. The view object defines the initial query executed by the business components.
The easiest way to create the data panel for Find mode operations is to bind a JUNavigationBar to the ADF Business Components view object that you want the data panel to search on. The navigation bar provides a Find button that the user selects to toggle the behavior of the ADF Swing control bindings for the ADF Swing form:
When Find mode is enabled on the data panel, the controls provide search criteria for a parameterized query on the queryable attributes of the ADF Business Components view object.
When Find mode is disabled, the controls provide data access to display and edit attributes of the view object.
The state of the Find-mode button is controlled by the hasFindButton property on the JUNavigationBar (true by default).
Note that all of the ADF Swing control bindings support the Find mode. If you want to create a data panel specifically for searches, limit your form to use these controls bound to ADF Business Components view object attributes to provide search criteria:
JTextField -- the user must enter a value
JCheckBox -- the user selects one of the predefined values
JSlider -- the user selects one of the predefined values
It is recommended that your data panel disable controls not in the above list when the user selects the Find mode. Disabling controls that do not support Find mode prevents the user from attempting to submit invalid search criteria.
Additionally, UI components that utilize an ADF list binding in navigation mode do not participate in the Find mode. However, if you drop a navigation-mode component, such as the databound ComboBox or JList, into a panel and activate Find mode, the component will not be disabled and will still permit the user to unintentionally display data in components that should appear empty in Find mode. To disable the interaction of the navigation component and the other components in Find mode, you can create a secondary iterator and edit the navigation-mode component's data binding to use that iterator.
To disable the interaction of the navigation component and the other components in Find mode:
In the user interface project, open the Java visual editor on the layout panel that contains the panels you want to navigate on.
In Java visual editor, click the Bindings tab and in the Executables list, click Create executable binding.
In the Insert Item dialog, select Iterator and click OK.
In the Create Iterator Binding dialog, select the data collection that your other components are bound to and enter a new name for the Iterator Id and click OK.
In the Bindings list, double-click the binding for the component that operates in navigation mode and select the new iterator in the control binding editor.
In addition to its basic data iteration functionality, the iterator binding also cooperates with the bound data collection to simplify implementing query-by-example capability for your application data by providing:
A collection of query-by-example criteria rows, and
An easy-to-use Find mode to work with these query criteria
In Oracle ADF, each data collection has an associated view criteria (ViewCriteria) collection of zero or more view criteria rows. Each view criteria row (ViewCriteriaRow) has the same attribute structure as a row in its related data collection, except that the attribute values are all treated as a String data type. This data type allows the user to enter query criteria containing comparison operators and wildcard characters.
For example, to indicate you want to find all departments whose department number is greater than 5 and whose department name matches the string 'ACC%', you would fill in the attributes of a view criteria row related to a DeptView collection (based on a query over the familiar DEPT table in the SCOTT schema) like this:
Deptno > 5
Dname ACC%
The iterator binding's Find mode makes it easy to create search pages that populate the attributes of the view criteria collection for query-by-example functionality. When an iterator binding is set to work in Find mode, it switches to use a different row set iterator over the related view criteria collection instead. This means that when Find mode is enabled, control bindings that reference the iterator binding will display and update attributes in the current view criteria row. Likewise, a range binding that references an iterator binding in Find mode allows you to render a table of current query-by-example view criteria rows.
When Find mode is disabled, the iterator binding switches back to work with its row set iterator over the data collection. This can be done explicitly by calling the iterator binding's setFindMode() method, or implicitly by calling its executeQuery() method.
Note:
By calling the createRow() method on the iterator binding's row set iterator while in Find mode, it is possible to create additional view criteria rows and then proceed to populate their attributes with additional criteria. The default semantics are that query-by-example criteria in the same view criteria rows are logically AND-ed together, while criteria resulting from separate view criteria rows are logically OR-ed together.
In actual practice, using multiple view criteria rows is not a common use case, but knowing it is possible helps to explain functionality. However, after the user enters Find mode, it is no longer possible to create the row on the original collection. Only when the user exits Find mode will it be possible to create a row that does not participate in the view criteria.
Although the ADF iterator binding provides its Find mode functionality independent of the kind of backend data control you choose, currently only the ADF Business Components data control makes automatic use of the view criteria collection of view criteria rows at runtime. It delegates the iterator binding's view criteria functionality to the underlying ADF view object, which implements the query-by-example criteria by automatically building appropriate SQL WHERE clause predicates based on the view criteria rows.
Other data control types would currently require a subclassed data control implementation containing some custom coding to read the query-by-example criteria from the view criteria collection and translate them into an appropriate runtime search implementation.
For details about the usage of view criteria in ADF Business Components, see the JavaDoc for the oracle.jbo.ViewCriteria class.
The radio button group is an ADF Swing JURadioButtonGroupPanel control that can be bound to an attribute group of a business service data collection through the ADF navigate binding. When the user changes the radio button selection, any controls in the containing panel that are also bound to the same data collection through its attributes will display from the selected data object.
To bind a radio button group to navigate data collections:
In the user interface project, open the Java visual editor on the desired data panel or form.
In the Data Controls panel, drag the data collection you want to bind to the radio button group control into the open form or panel.
From the Add Child popup list, select Radio Button Group.
JDeveloper adds code to the class file to bind the JURadioButtonGroupPanel to the collection:
jURadioButtonGroupPanel1.setModel((JUButtonGroupBinding)
panelBinding.bindUIControl("MyDataCollection", jURadioButtonGroupPanel1));
In the List binding editor, choose the display attributes you want to use with the radio button panel.
To change the data binding of an radio button group:
Open the form or panel containing the JURadioButtonGroupPanel control in the Java visual editor.
Right-click the JURadioButtonGroupPanel control you want to change and select Edit Bindings from the menu.
The Edit List Binding dialog displays.
To customize the layout of the radio button panel:
The default layout for the radio buttons is by row, but you can change the layout through the rowCount and columnCount properties of the panel.
For example, to display the radio button selections in columns:
Set rowCount to 0, and columnCount to the desired number of columns.
The Shuttle control is an ADF Swing JUShuttlePanel control that can be bound to an attribute of a business service collection through the ADF Swing list binding. The JUShuttlePanel control allows the user to make multiple selections for the displayed shuttle list.
To insert a databound shuttle panel into a form or panel:
In the user interface project, open the form or data panel in the Java visual editor.
In the Data Controls panel, drag the collection you want to bind to the JUShuttlePanel control into the open form or panel.
From the Add Child popup list, select Shuttle.
JDeveloper adds code to the class file to reference the DCShuttle binding definition in the page definition file associated with the form:
myjUShuttlePanel1.setModel((JUShuttleModel)
(panelBinding.findNestedPanelBinding("DCShuttle")));
To change the data binding of a shuttle panel in a form or panel:
Open the form or panel containing the JUShuttlePanel control in the Java visual editor.
Right-click the JUShuttlePanel control you want to change and select Edit Bindings from the menu.
The Edit Shuttle Binding dialog displays.
The status bar is an ADF Swing JUStatusBar control that relies on a panel binding to display status information for the UI control that shares its panel binding and has the current focus in the displayed form or panel.
To insert a status bar into a form or panel:
In the user interface project, open the form or data panel in the Java visual editor.
In the Data Controls panel, drag the collection you want to bind to the JUStatusBar control into the open form or panel.
From the Add Child popup list, select Status Bar.
JDeveloper adds code to the class file to define a panel binding for the status bar:
myjUStatusBar1.setModel(JUStatusBar.createPanelBinding(panelBinding, jUStatusBar1));