Skip to content

Commit dab6644

Browse files
ptzieglerptziegler
committed
Migrate Swing Documentation from HTML to AsciiDoc
Contributes to #642
1 parent e8e4cbb commit dab6644

File tree

73 files changed

+2761
-3772
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

73 files changed

+2761
-3772
lines changed

‎org.eclipse.wb.swing.doc.user/html-src/features/swing/data_binding/create_data_binding_wizard.adoc‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
ifdef::env-github[]
2+
:imagesdir: ../../../../html/features/swing/data_binding
3+
endif::[]
4+
5+
= Create Data Binding Wizard
6+
7+
The tool provides two ways to quickly create new Data Bindings: the *Data Bindings* menu and the *bindings property* in
8+
the property pane.
9+
10+
[cols="50%,50%", options="header"]
11+
|===
12+
|
13+
Data Binding Menu
14+
|
15+
Bindings Property
16+
|
17+
The *Data Bindings* menu provides the ability to quickly create a data binding for a widget. If the widget does not have
18+
any data bindings, the menu immediately cascades out to show the available properties of the widget that can be bound to
19+
a model property. If the widget has existing data bindings, those are shown at the top of the cascaded menu and a list
20+
of widget properties is shown in a submenu. Clicking on an unbound property will open the *Create Data Binding* wizard.
21+
|
22+
The *bindings property* in the property pane opens up to show a list of all bindable properties of the widget. Clicking
23+
the image:images/dot-dot-dot-button.gif[image] button next to an unbound property will open the *Create Data Binding*
24+
wizard.
25+
a|
26+
image:images/data_binding_menu.gif[image]
27+
a|
28+
image:images/data_binding_property_pane1.gif[image]
29+
|===
30+
31+
== Choose Model
32+
33+
The first page of the *Create Data Binding* wizard is used to select the model and property to bind the selected target
34+
property to. Two types of targets and models are supported:
35+
image:images/data_binding_beans_button.gif[image] *Beans* and image:images/data_binding_widgets_button.gif[image]
36+
*Widgets*. The filter field above the list can be used to filter the list of items. The
37+
image:images/clear_filter_button.gif[image] clear button can be used to clear the filter and restore the full list.
38+
39+
[cols="50%, 50%"]
40+
|===
41+
.2+a|
42+
image:images/create_data_binding1.gif[image]
43+
a|
44+
- image:images/data_binding_beans_button.gif[image] *Beans*: any field of the current compilation unit may be selected.
45+
46+
image:images/create_data_binding_model_beans.gif[image]
47+
48+
a|
49+
- *image:images/data_binding_widgets_button.gif[image] Widgets*: any widget in the current compilation unit may be
50+
selected.
51+
52+
image:images/create_data_binding_model_widgets.gif[image]
53+
|===
54+
55+
When any *Model* object is selected, its properties (bean fields or standard Swing widget properties) are shown in the
56+
associated *Properties* list. Properties may be expanded to show their nested attributes. A drop down filter menu is
57+
available to filter the Property list by type and hide or show the advanced properties. Supported filters are *String*,
58+
*Boolean*, *Numbers*, *Color*, *Font* and *Image*.
59+
60+
--
61+
image:images/properties.gif[image]
62+
image:images/properties_expanded.gif[image]
63+
image:images/properties_filtered.gif[image]
64+
image:images/properties_advanced.gif[image]
65+
image:images/filter_button.gif[image]
66+
--
67+
68+
Once the model property has been selected, click the *Finish* button to create a new data binding using default options.
69+
If you wish to customize the properties of the data binding, click the *Next* button to go to the second page of the
70+
wizard.
71+
72+
== Properties
73+
74+
The second page of the *Create Data Binding* wizard is used to customize the properties of the data binding itself. When
75+
creating a binding, the update strategy from *target to model* and *model to target* may be specified as well as any
76+
strategy-specific properties (validators and converters).
77+
78+
[cols="50%,50%"]
79+
|===
80+
.2+a|
81+
image:images/create_data_binding2.gif[image]
82+
a|
83+
When the Target or Model is a Text widget and the text property is selected, the triggering event may be specified as
84+
*Swing.Modify*, *Swing.FocusOut* or *Swing.NONE*.
85+
86+
image:images/text_events.gif[image]
87+
a|
88+
Predefined update value strategies - *READ_ONCE*, *READ* and *READ_WRITE* - may be selected.
89+
90+
image:images/update_value_strategy.gif[image]
91+
|===
92+
93+
== Source
94+
95+
Clicking the *Finish* button will generate the necessary data binding code which may then be seen in the *Source* view.
96+
An *initDataBindings()* method is created, if it does not already exist and a call to that method is added to the end of
97+
the widget creation process. Within the *initDataBindings()* method, any needed bean properties are created followed by
98+
the creation of each binding.
99+
100+
image:images/data_binding_source2.gif[image]
101+
102+
WARNING: _do not edit the *initDataBinding()* method by hand (without carefully matching the code generation pattern
103+
used by the tool) as it will be regenerated in its entirety any time the tool needs to add, remove or update a data
104+
binding._

‎org.eclipse.wb.swing.doc.user/html-src/features/swing/data_binding/edit_data_binding_dialog.adoc‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
ifdef::env-github[]
2+
:imagesdir: ../../../../html/features/swing/data_binding
3+
endif::[]
4+
5+
= Edit Data Binding Dialog
6+
7+
The tool provides two ways to quickly edit existing Data Bindings: the *Data Bindings* menu and the *bindings property*
8+
in the property pane.
9+
10+
[cols="50%,50%", options="header"]
11+
|===
12+
| Data Binding Menu
13+
| Bindings Property
14+
a|
15+
The *Data Bindings* menu provides the ability to quickly edit a data binding for a widget. If the widget has existing
16+
data bindings, those are shown at the top of the cascaded menu and a list of widget properties is shown in a submenu.
17+
Clicking on a bound property will open the *Edit Data Binding* dialog.
18+
a|
19+
The *bindings property* in the property pane opens up to show a list of all bindable properties of the widget. Clicking
20+
the image:images/dot-dot-dot-button.gif[image] button next to a bound property will open the *Edit Data Binding* dialog.
21+
|
22+
image:images/data_binding_menu2.gif[image]
23+
|
24+
image:images/data_binding_property_pane2.gif[image]
25+
26+
|
27+
image:images/edit_data_binding1.gif[image]
28+
a|
29+
The *Edit Data Binding* dialog is used to customize the properties of the data binding itself. When editing a binding,
30+
the update strategy from *target to model* and *model to target* may be specified as well as any strategy-specific
31+
properties (validators and converters).
32+
33+
When the Target or Model is a Text widget and the text property is selected, the triggering event may be specified as
34+
*Swing.Modify*, *Swing.FocusOut* or *Swing.NONE*.
35+
36+
image:images/text_events.gif[image]
37+
|
38+
image:images/edit_data_binding2.gif[image]
39+
a|
40+
Predefined update value strategies - *READ_ONCE*, *READ* and *READ_WRITE* - may be selected.
41+
42+
image:images/update_value_strategy.gif[image]
43+
|===
44+
45+
When binding to a *<EL Expression>*, a text field is provided where the expression may be entered.
46+
47+
image:images/bind_properties_swing2.gif[image]
48+
49+
== Source
50+
51+
Clicking the *Finish* button will generate the necessary data binding code which may then be seen in the *Source* view.
52+
An *initDataBindings()* method is created, if it does not already exist and a call the that method is added to the end
53+
of the widget creation process. Within the *initDataBindings()* method, any needed bean properties are created followed
54+
by the creation of each binding.
55+
56+
image:images/data_binding_source2.gif[image]
57+
58+
WARNING: _do not edit the *initDataBinding()* method by hand (without carefully matching the code generation pattern
59+
used by the tool) as it will be regenerated in its entirety any time the tool needs to add, remove or update a data
60+
binding._

‎org.eclipse.wb.swing.doc.user/html-src/features/swing/data_binding/example.adoc‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
ifdef::env-github[]
2+
:imagesdir: ../../../../html/features/swing/data_binding
3+
endif::[]
4+
5+
= Swing Data Binding Example
6+
7+
As an example of how the the data binding tools can be used, consider the following *Phone Book* example. The phone book
8+
manages a set of phone groups. Each phone group in turn holds onto one or more persons. For each person, various e-mail
9+
and phone contact information is maintained. Editing a person's description should update the same data shown in the
10+
list. The final code for the *Phone Book* project is available link:SwingBindingsTest.zip[here].
11+
12+
1. Use Designer to create the skeleton of the *JPhoneBook.java* class
13+
+
14+
image:images/example1.gif[image]
15+
16+
2. Create the following model classes:
17+
- Class *Person* with properties: *name*, *email*, *phone*, *mobilePhone1*, *mobilePhone2*
18+
- Class *PhoneGroup* with properties: *name*, *persons*
19+
- Class *PhoneGroups* with properties: *groups*
20+
21+
3. Add the following to the *JPhoneBook* class:
22+
+
23+
[source,java]
24+
----
25+
private PhoneGroups m_groups = new PhoneGroups();
26+
----
27+
And add some initial data:
28+
+
29+
[source,java]
30+
----
31+
PhoneGroup group1 = new PhoneGroup("Developer Team");
32+
m_groups.addGroup(group1);
33+
group1.addPerson(new Person("Konstantin Scheglov", "kosta@nospam.com", "1234567890", "", ""));
34+
group1.addPerson(new Person("Alexander Mitin", "mitin@nospam.com", "", "0987654321", ""));
35+
group1.addPerson(new Person("Alexander Lobas", "lobas@nospam.com", "", "", "111-222-333-00"));
36+
----
37+
38+
4. Set the content for the group viewer. Click the *Bindings* tab in the editor. Select *m_groupList* in the
39+
*Targets (Widgets)* list, *<Self Object>* in the *Target Properties* list, select *m_groups* in the
40+
image:images/data_binding_beans_button.gif[image] *Model (Beans)* list, and *groups* in the *Model Properties* list.
41+
+
42+
image:../../../wizards/swing/images/data_binding_tab.gif[image]
43+
+
44+
image:images/example2.gif[image]
45+
46+
5. Click the image:images/binding_button.gif[image] *Bind* button to open the *Create Data Binding* dialog.
47+
*m_groups.group* contains elements of type *PhoneGroup*, so select the type *PhoneGroup* and its *<EL Expression>*
48+
property. In the EL Expression field, type "$\{name} (\{$personCount})". Note that selecting the *name* property would
49+
result in just the name of the group being displayed. You can use EL Expressions to create more complex results. In this
50+
case, we can show the name plus the number of people in the group.
51+
+
52+
image:images/example3.gif[image]image:images/example4.gif[image]
53+
54+
6. Click *OK* to see *m_groups.groups* bound to *m_groupsList* in the table. You can also see that the detail binding
55+
between *m_groupsList* and the *EL Expression* has also been created.
56+
+
57+
image:images/example5.gif[image]
58+
59+
7. Run the application to see that the list of phone groups is populated and that each group shows its person count.
60+
+
61+
image:images/example6.gif[image] +
62+
63+
8. Next we would like selecting a group to show all of its contained persons. Switch back to the *Bindings* tab. Select
64+
the *<Self Object>* of the *m_personTable* in the *Target Widget* list and *m_groupList* and *selectedElement/persons*
65+
in the *Model Widget* list and click the image:images/binding_button.gif[image] *Bind* button to open the
66+
*Create Data Binding* dialog.
67+
+
68+
image:images/example7.gif[image] image:images/example8.gif[image]
69+
70+
9. We need to show the properties of a *Person* object in *m_personTable*, so click the *Add* button to add a table
71+
column binding for each property (*name*, *email*, *phone*, *mobilePhone1* and *mobilePhone2*). You can order the
72+
*Person* properties using the *<<* and *>>* buttons.
73+
+
74+
image:images/example9.gif[image]image:images/example10.gif[image]
75+
76+
10. Click *OK* twice and run the application. See that selecting a group now updates the *Persons* list.
77+
+
78+
image:images/example11.gif[image]
79+
80+
11. Switch back to the *Bindings* tab. Next we need to bind *selectedElement* of the *m_personTable* (a Person object)
81+
into the various text editors.
82+
+
83+
image:images/example12.gif[image]
84+
85+
12. Select the first *Text* widget (*m_nameTextField*) and its *text* property and the *m_personTable* and its
86+
*selectedElement/name* property. Click the image:images/binding_button.gif[image] *Bind* button to open the
87+
*Create Data Binding* dialog. Leave everything set to the defaults and click the *OK* button.
88+
+
89+
image:images/example13.gif[image]
90+
91+
13. Bind each *selectedElement* property to its associated *Text* field.
92+
+
93+
image:images/example14.gif[image]
94+
95+
14. Run the application. See that selecting a group updates the *Persons* list and selecting a *Person* now updates each
96+
of the *Text* fields.
97+
+
98+
image:images/example15.gif[image]
99+
100+
15. Also note that changing any of the data in the text fields immediately updates the data in the table.
101+
*The magic of data binding!*
102+
+
103+
image:images/example16.gif[image]

‎org.eclipse.wb.swing.doc.user/html-src/features/swing/data_binding/index.adoc‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
ifdef::env-github[]
2+
:imagesdir: ../../../../html/features/swing/data_binding
3+
endif::[]
4+
5+
= Swing Data Binding
6+
7+
NOTE: _In order to use Swing Data Binding (JSR 295), you must first add the Swing Data Binding jar
8+
(e.g., beansbinding-1.2.1.jar) to your classpath._
9+
10+
The tool can create new *Data Bindings* in several different ways:
11+
12+
- Click the xref:#DataBindingTab[*Bindings*] tab in the editor to created and edit the bindings.
13+
- Right-clicking on a widget and selecting the xref:#DataBindingMenu[*Data Binding*] menu.
14+
- Expanding the xref:#BindingsProperty[*bindings*] property in the property pane.
15+
- Use the xref:#AutomaticWizard[*Swing Automatic Data Binding*] wizard to create a complete user interface from a domain
16+
(bean) class.
17+
18+
The tool will generate or update any necessary data binding code which may then be seen in the xref:#Source[*Source*]
19+
view.
20+
21+
Detailed link:example.html[data binding example] code is available link:SwingBindingsTest.zip[here].
22+
23+
[#DataBindingTab]
24+
== Data Binding Tab
25+
26+
Click the *Bindings* tab in the editor to created and edit data bindings.
27+
28+
image:../../../wizards/swing/images/data_binding_tab.gif[image]
29+
30+
image:../../../wizards/swing/images/automatic_data_binding8.gif[image]
31+
32+
The *Bindings* tab supports the creation xref:swing_bindings.adoc[*JSR 295 Swing data bindings*].
33+
34+
[#DataBindingMenu]
35+
== Data Binding Menu
36+
37+
The *Data Bindings* menu provides the ability to quickly create or edit data bindings for a widget. If the widget does
38+
not have any data bindings, the menu immediately cascades out to show the available properties of the widget that can be
39+
bound to a model property. If the widget has existing data bindings, those are shown at the top of the cascaded menu
40+
followed by a separator and a list of widget properties. Clicking on an unbound property will open the
41+
xref:create_data_binding_wizard.adoc[*Create Data Binding*] wizard while clicking a bound property will open the
42+
xref:edit_data_binding_dialog.adoc[*Edit Data Binding*] dialog.
43+
44+
image:images/data_binding_menu.gif[image].
45+
46+
[#BindingsProperty]
47+
== Bindings Property
48+
49+
The *bindings property* in the property pane opens up to show a list of all bindable properties of the widget. Clicking
50+
the image:images/dot-dot-dot-button.gif[image] button next to an unbound property will open the
51+
xref:create_data_binding_wizard.adoc[*Create Data Binding*] wizard while clicking the
52+
image:images/dot-dot-dot-button.gif[image] button next to a bound property will open the
53+
xref:edit_data_binding_dialog.adoc[*Edit Data Binding*] dialog.
54+
55+
image:images/data_binding_property_pane2.gif[image].
56+
57+
[#AutomaticWizard]
58+
== Automatic Data Binding Wizard
59+
60+
The xref:../../../wizards/swing/automatic_databinding.adoc[*Swing Automatic Data Binding*] wizard can be used to create
61+
new user interface classes (Composites, Dialogs or Windows) complete with widgets, layouts and data bindings from
62+
arbitrary domain model (bean) classes.
63+
64+
--
65+
image:../../../wizards/swing/images/automatic_data_binding2.gif[image]
66+
image:../../../wizards/swing/images/automatic_data_binding5.gif[image]
67+
--
68+
69+
[#IconDecorator]
70+
== Icon Decorator
71+
72+
Any widget with a data binding assigned to will show up in the component tree with an icon decorator:
73+
image:images/icon_decorator2.gif[image]
74+
image:images/icon_decorator3.gif[image]
75+
76+
image:images/icon_decorator.gif[image]
77+
78+
[#Source]
79+
== Source
80+
81+
*The tool* will generate or update any necessary data binding code which may then be seen in the *Source* view. An
82+
*initDataBindings()* method is created, if it does not already exist and a call to that method is added to the end of
83+
the widget creation process.
84+
85+
Within the *initDataBindings()* method, any needed bean properties are created followed by the creation of each binding.
86+
87+
image:images/data_binding_source.gif[image]
88+
89+
WARNING: _do not edit the *initDataBinding()* method by hand (without carefully matching the code generation pattern
90+
used by the tool) as it will be regenerated in its entirety any time the tool needs to add, remove or update a data
91+
binding._

0 commit comments

Comments
 (0)