Skip to content

Migrate Swing Documentation from HTML to AsciiDoc #1333

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ptziegler merged 1 commit into from
Jan 8, 2026
Merged

Migrate Swing Documentation from HTML to AsciiDoc #1333

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions ...g.doc.user/html-src/features/swing/data_binding/create_data_binding_wizard.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
ifdef::env-github[]
:imagesdir: ../../../../html/features/swing/data_binding
endif::[]

= Create Data Binding Wizard

The tool provides two ways to quickly create new Data Bindings: the *Data Bindings* menu and the *bindings property* in
the property pane.

[cols="50%,50%", options="header"]
|===
|
Data Binding Menu
|
Bindings Property
|
The *Data Bindings* menu provides the ability to quickly create a data binding for a widget. If the widget does not have
any data bindings, the menu immediately cascades out to show the available properties of the widget that can be bound to
a model property. If the widget has existing data bindings, those are shown at the top of the cascaded menu and a list
of widget properties is shown in a submenu. Clicking on an unbound property will open the *Create Data Binding* wizard.
|
The *bindings property* in the property pane opens up to show a list of all bindable properties of the widget. Clicking
the image:images/dot-dot-dot-button.gif[image] button next to an unbound property will open the *Create Data Binding*
wizard.
a|
image:images/data_binding_menu.gif[image]
a|
image:images/data_binding_property_pane1.gif[image]
|===

== Choose Model

The first page of the *Create Data Binding* wizard is used to select the model and property to bind the selected target
property to. Two types of targets and models are supported:
image:images/data_binding_beans_button.gif[image] *Beans* and image:images/data_binding_widgets_button.gif[image]
*Widgets*. The filter field above the list can be used to filter the list of items. The
image:images/clear_filter_button.gif[image] clear button can be used to clear the filter and restore the full list.

[cols="50%, 50%"]
|===
.2+a|
image:images/create_data_binding1.gif[image]
a|
- image:images/data_binding_beans_button.gif[image] *Beans*: any field of the current compilation unit may be selected.

image:images/create_data_binding_model_beans.gif[image]

a|
- *image:images/data_binding_widgets_button.gif[image] Widgets*: any widget in the current compilation unit may be
selected.

image:images/create_data_binding_model_widgets.gif[image]
|===

When any *Model* object is selected, its properties (bean fields or standard Swing widget properties) are shown in the
associated *Properties* list. Properties may be expanded to show their nested attributes. A drop down filter menu is
available to filter the Property list by type and hide or show the advanced properties. Supported filters are *String*,
*Boolean*, *Numbers*, *Color*, *Font* and *Image*.

--
image:images/properties.gif[image]
image:images/properties_expanded.gif[image]
image:images/properties_filtered.gif[image]
image:images/properties_advanced.gif[image]
image:images/filter_button.gif[image]
--

Once the model property has been selected, click the *Finish* button to create a new data binding using default options.
If you wish to customize the properties of the data binding, click the *Next* button to go to the second page of the
wizard.

== Properties

The second page of the *Create Data Binding* wizard is used to customize the properties of the data binding itself. When
creating a binding, the update strategy from *target to model* and *model to target* may be specified as well as any
strategy-specific properties (validators and converters).

[cols="50%,50%"]
|===
.2+a|
image:images/create_data_binding2.gif[image]
a|
When the Target or Model is a Text widget and the text property is selected, the triggering event may be specified as
*Swing.Modify*, *Swing.FocusOut* or *Swing.NONE*.

image:images/text_events.gif[image]
a|
Predefined update value strategies - *READ_ONCE*, *READ* and *READ_WRITE* - may be selected.

image:images/update_value_strategy.gif[image]
|===

== Source

Clicking the *Finish* button will generate the necessary data binding code which may then be seen in the *Source* view.
An *initDataBindings()* method is created, if it does not already exist and a call to that method is added to the end of
the widget creation process. Within the *initDataBindings()* method, any needed bean properties are created followed by
the creation of each binding.

image:images/data_binding_source2.gif[image]

WARNING: _do not edit the *initDataBinding()* method by hand (without carefully matching the code generation pattern
used by the tool) as it will be regenerated in its entirety any time the tool needs to add, remove or update a data
binding._
60 changes: 60 additions & 0 deletions ...ing.doc.user/html-src/features/swing/data_binding/edit_data_binding_dialog.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
ifdef::env-github[]
:imagesdir: ../../../../html/features/swing/data_binding
endif::[]

= Edit Data Binding Dialog

The tool provides two ways to quickly edit existing Data Bindings: the *Data Bindings* menu and the *bindings property*
in the property pane.

[cols="50%,50%", options="header"]
|===
| Data Binding Menu
| Bindings Property
a|
The *Data Bindings* menu provides the ability to quickly edit a data binding for a widget. If the widget has existing
data bindings, those are shown at the top of the cascaded menu and a list of widget properties is shown in a submenu.
Clicking on a bound property will open the *Edit Data Binding* dialog.
a|
The *bindings property* in the property pane opens up to show a list of all bindable properties of the widget. Clicking
the image:images/dot-dot-dot-button.gif[image] button next to a bound property will open the *Edit Data Binding* dialog.
|
image:images/data_binding_menu2.gif[image]
|
image:images/data_binding_property_pane2.gif[image]

|
image:images/edit_data_binding1.gif[image]
a|
The *Edit Data Binding* dialog is used to customize the properties of the data binding itself. When editing a binding,
the update strategy from *target to model* and *model to target* may be specified as well as any strategy-specific
properties (validators and converters).

When the Target or Model is a Text widget and the text property is selected, the triggering event may be specified as
*Swing.Modify*, *Swing.FocusOut* or *Swing.NONE*.

image:images/text_events.gif[image]
|
image:images/edit_data_binding2.gif[image]
a|
Predefined update value strategies - *READ_ONCE*, *READ* and *READ_WRITE* - may be selected.

image:images/update_value_strategy.gif[image]
|===

When binding to a *<EL Expression>*, a text field is provided where the expression may be entered.

image:images/bind_properties_swing2.gif[image]

== Source

Clicking the *Finish* button will generate the necessary data binding code which may then be seen in the *Source* view.
An *initDataBindings()* method is created, if it does not already exist and a call the that method is added to the end
of the widget creation process. Within the *initDataBindings()* method, any needed bean properties are created followed
by the creation of each binding.

image:images/data_binding_source2.gif[image]

WARNING: _do not edit the *initDataBinding()* method by hand (without carefully matching the code generation pattern
used by the tool) as it will be regenerated in its entirety any time the tool needs to add, remove or update a data
binding._
103 changes: 103 additions & 0 deletions org.eclipse.wb.swing.doc.user/html-src/features/swing/data_binding/example.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
ifdef::env-github[]
:imagesdir: ../../../../html/features/swing/data_binding
endif::[]

= Swing Data Binding Example

As an example of how the the data binding tools can be used, consider the following *Phone Book* example. The phone book
manages a set of phone groups. Each phone group in turn holds onto one or more persons. For each person, various e-mail
and phone contact information is maintained. Editing a person's description should update the same data shown in the
list. The final code for the *Phone Book* project is available link:SwingBindingsTest.zip[here].

1. Use Designer to create the skeleton of the *JPhoneBook.java* class
+
image:images/example1.gif[image]

2. Create the following model classes:
- Class *Person* with properties: *name*, *email*, *phone*, *mobilePhone1*, *mobilePhone2*
- Class *PhoneGroup* with properties: *name*, *persons*
- Class *PhoneGroups* with properties: *groups*

3. Add the following to the *JPhoneBook* class:
+
[source,java]
----
private PhoneGroups m_groups = new PhoneGroups();
----
And add some initial data:
+
[source,java]
----
PhoneGroup group1 = new PhoneGroup("Developer Team");
m_groups.addGroup(group1);
group1.addPerson(new Person("Konstantin Scheglov", "kosta@nospam.com", "1234567890", "", ""));
group1.addPerson(new Person("Alexander Mitin", "mitin@nospam.com", "", "0987654321", ""));
group1.addPerson(new Person("Alexander Lobas", "lobas@nospam.com", "", "", "111-222-333-00"));
----

4. Set the content for the group viewer. Click the *Bindings* tab in the editor. Select *m_groupList* in the
*Targets (Widgets)* list, *<Self Object>* in the *Target Properties* list, select *m_groups* in the
image:images/data_binding_beans_button.gif[image] *Model (Beans)* list, and *groups* in the *Model Properties* list.
+
image:../../../wizards/swing/images/data_binding_tab.gif[image]
+
image:images/example2.gif[image]

5. Click the image:images/binding_button.gif[image] *Bind* button to open the *Create Data Binding* dialog.
*m_groups.group* contains elements of type *PhoneGroup*, so select the type *PhoneGroup* and its *<EL Expression>*
property. In the EL Expression field, type "$\{name} (\{$personCount})". Note that selecting the *name* property would
result in just the name of the group being displayed. You can use EL Expressions to create more complex results. In this
case, we can show the name plus the number of people in the group.
+
image:images/example3.gif[image]image:images/example4.gif[image]

6. Click *OK* to see *m_groups.groups* bound to *m_groupsList* in the table. You can also see that the detail binding
between *m_groupsList* and the *EL Expression* has also been created.
+
image:images/example5.gif[image]

7. Run the application to see that the list of phone groups is populated and that each group shows its person count.
+
image:images/example6.gif[image] +

8. Next we would like selecting a group to show all of its contained persons. Switch back to the *Bindings* tab. Select
the *<Self Object>* of the *m_personTable* in the *Target Widget* list and *m_groupList* and *selectedElement/persons*
in the *Model Widget* list and click the image:images/binding_button.gif[image] *Bind* button to open the
*Create Data Binding* dialog.
+
image:images/example7.gif[image] image:images/example8.gif[image]

9. We need to show the properties of a *Person* object in *m_personTable*, so click the *Add* button to add a table
column binding for each property (*name*, *email*, *phone*, *mobilePhone1* and *mobilePhone2*). You can order the
*Person* properties using the *<<* and *>>* buttons.
+
image:images/example9.gif[image]image:images/example10.gif[image]

10. Click *OK* twice and run the application. See that selecting a group now updates the *Persons* list.
+
image:images/example11.gif[image]

11. Switch back to the *Bindings* tab. Next we need to bind *selectedElement* of the *m_personTable* (a Person object)
into the various text editors.
+
image:images/example12.gif[image]

12. Select the first *Text* widget (*m_nameTextField*) and its *text* property and the *m_personTable* and its
*selectedElement/name* property. Click the image:images/binding_button.gif[image] *Bind* button to open the
*Create Data Binding* dialog. Leave everything set to the defaults and click the *OK* button.
+
image:images/example13.gif[image]

13. Bind each *selectedElement* property to its associated *Text* field.
+
image:images/example14.gif[image]

14. Run the application. See that selecting a group updates the *Persons* list and selecting a *Person* now updates each
of the *Text* fields.
+
image:images/example15.gif[image]

15. Also note that changing any of the data in the text fields immediately updates the data in the table.
*The magic of data binding!*
+
image:images/example16.gif[image]
91 changes: 91 additions & 0 deletions org.eclipse.wb.swing.doc.user/html-src/features/swing/data_binding/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
ifdef::env-github[]
:imagesdir: ../../../../html/features/swing/data_binding
endif::[]

= Swing Data Binding

NOTE: _In order to use Swing Data Binding (JSR 295), you must first add the Swing Data Binding jar
(e.g., beansbinding-1.2.1.jar) to your classpath._

The tool can create new *Data Bindings* in several different ways:

- Click the xref:#DataBindingTab[*Bindings*] tab in the editor to created and edit the bindings.
- Right-clicking on a widget and selecting the xref:#DataBindingMenu[*Data Binding*] menu.
- Expanding the xref:#BindingsProperty[*bindings*] property in the property pane.
- Use the xref:#AutomaticWizard[*Swing Automatic Data Binding*] wizard to create a complete user interface from a domain
(bean) class.

The tool will generate or update any necessary data binding code which may then be seen in the xref:#Source[*Source*]
view.

Detailed link:example.html[data binding example] code is available link:SwingBindingsTest.zip[here].

[#DataBindingTab]
== Data Binding Tab

Click the *Bindings* tab in the editor to created and edit data bindings.

image:../../../wizards/swing/images/data_binding_tab.gif[image]

image:../../../wizards/swing/images/automatic_data_binding8.gif[image]

The *Bindings* tab supports the creation xref:swing_bindings.adoc[*JSR 295 Swing data bindings*].

[#DataBindingMenu]
== Data Binding Menu

The *Data Bindings* menu provides the ability to quickly create or edit data bindings for a widget. If the widget does
not have any data bindings, the menu immediately cascades out to show the available properties of the widget that can be
bound to a model property. If the widget has existing data bindings, those are shown at the top of the cascaded menu
followed by a separator and a list of widget properties. Clicking on an unbound property will open the
xref:create_data_binding_wizard.adoc[*Create Data Binding*] wizard while clicking a bound property will open the
xref:edit_data_binding_dialog.adoc[*Edit Data Binding*] dialog.

image:images/data_binding_menu.gif[image].

[#BindingsProperty]
== Bindings Property

The *bindings property* in the property pane opens up to show a list of all bindable properties of the widget. Clicking
the image:images/dot-dot-dot-button.gif[image] button next to an unbound property will open the
xref:create_data_binding_wizard.adoc[*Create Data Binding*] wizard while clicking the
image:images/dot-dot-dot-button.gif[image] button next to a bound property will open the
xref:edit_data_binding_dialog.adoc[*Edit Data Binding*] dialog.

image:images/data_binding_property_pane2.gif[image].

[#AutomaticWizard]
== Automatic Data Binding Wizard

The xref:../../../wizards/swing/automatic_databinding.adoc[*Swing Automatic Data Binding*] wizard can be used to create
new user interface classes (Composites, Dialogs or Windows) complete with widgets, layouts and data bindings from
arbitrary domain model (bean) classes.

--
image:../../../wizards/swing/images/automatic_data_binding2.gif[image]
image:../../../wizards/swing/images/automatic_data_binding5.gif[image]
--

[#IconDecorator]
== Icon Decorator

Any widget with a data binding assigned to will show up in the component tree with an icon decorator:
image:images/icon_decorator2.gif[image]
image:images/icon_decorator3.gif[image]

image:images/icon_decorator.gif[image]

[#Source]
== Source

*The tool* will generate or update any necessary data binding code which may then be seen in the *Source* view. An
*initDataBindings()* method is created, if it does not already exist and a call to that method is added to the end of
the widget creation process.

Within the *initDataBindings()* method, any needed bean properties are created followed by the creation of each binding.

image:images/data_binding_source.gif[image]

WARNING: _do not edit the *initDataBinding()* method by hand (without carefully matching the code generation pattern
used by the tool) as it will be regenerated in its entirety any time the tool needs to add, remove or update a data
binding._
Loading
Loading