Bug 16: [Doc] Update documentation with Papyrus Reference

Ticket: https://github.com/PapyrusSirius/papyrus-desktop/issues/16
Change-Id: I212ecc597ec7565fbfce1a45cc22c5717fcbaccf
Signed-off-by: Glenn Plouhinec <glenn.plouhinec@obeo.fr>

13 files changed, 92 insertions, 0 deletions

diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/dev/papyrusReferenceWidget.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/dev/papyrusReferenceWidget.png
new file mode 100644
index 000000000..3afb76244
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/dev/papyrusReferenceWidget.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/dev/papyrusReferenceWidget_PropertiesView.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/dev/papyrusReferenceWidget_PropertiesView.png
new file mode 100644
index 000000000..40365ead1
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/dev/papyrusReferenceWidget_PropertiesView.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addButtonDialog.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addButtonDialog.png
new file mode 100644
index 000000000..778bf9f9a
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addButtonDialog.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addButtonMultiRefWithoutContainment.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addButtonMultiRefWithoutContainment.png
new file mode 100644
index 000000000..8f84248d1
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addButtonMultiRefWithoutContainment.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addWizardDialog.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addWizardDialog.png
new file mode 100644
index 000000000..be202fdd3
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/addWizardDialog.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/browseButtonMultiRefWithoutContainment.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/browseButtonMultiRefWithoutContainment.png
new file mode 100644
index 000000000..947c8ce16
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/browseButtonMultiRefWithoutContainment.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/editButtonDialog.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/editButtonDialog.png
new file mode 100644
index 000000000..796906c0f
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/editButtonDialog.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/mono-valuedReferenceWithContainment_example.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/mono-valuedReferenceWithContainment_example.png
new file mode 100644
index 000000000..d438bac73
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/mono-valuedReferenceWithContainment_example.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/mono-valuedReferenceWithoutContainment_example.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/mono-valuedReferenceWithoutContainment_example.png
new file mode 100644
index 000000000..f213c767e
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/mono-valuedReferenceWithoutContainment_example.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/multi-valuedReferenceWithContainment_example.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/multi-valuedReferenceWithContainment_example.png
new file mode 100644
index 000000000..967a8ac6c
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/multi-valuedReferenceWithContainment_example.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/multi-valuedReferenceWithoutContainment_example.png b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/multi-valuedReferenceWithoutContainment_example.png
new file mode 100644
index 000000000..e03c8c8c7
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/image/user/multi-valuedReferenceWithoutContainment_example.png
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/src/site/mediawiki/papyrus-sirius-devDoc.mediawiki b/plugins/doc/org.eclipse.papyrus.sirius.doc/src/site/mediawiki/papyrus-sirius-devDoc.mediawiki
index f9590782f..e1587a656 100755
--- a/plugins/doc/org.eclipse.papyrus.sirius.doc/src/site/mediawiki/papyrus-sirius-devDoc.mediawiki
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/src/site/mediawiki/papyrus-sirius-devDoc.mediawiki
@@ -364,3 +364,26 @@ EEF Properties view display same properties view to user than by using Papyrus P
 
 The EEF Properties View can be configured by editing the viewpoint specification model (VSM) available in ''org.eclipse.papyrus.sirius.properties.uml/description/umlProperties.odesign''. 
 Fore more details about configuration, developer can see documentation about Sirius Properties view in Help content (Sirius>Sirius Specifier Manual>Properties View).
+
+Given the fact that some controls displayed in properties are very specific for some element, some specific widget have been created.
+In this way, complex Properties view will match exactly with the need of specifiers.
+The next part will detail all these new controls (general controls usable with EEF (Text, Checkbox, Radio, Select, List, Hyperlink, Button, Reference, ...) are described in the EEF documentation: EEF > Language > Widgets)
+
+== Papyrus Reference Widget ==
+
+In order to edit mono-valued and multi-valued references with some specific behaviors, an advanced widget has been created.
+This "Papyrus Reference" advanced widget is an implementation of the Sirius "Reference" Widget.
+Compared to the existing Sirius widget, this widget brings some new evolutions by overriding some user behaviors:
+
+* User can double click on an element of the reference to display its properties in a new properties dialog.
+* After clicking on ''Add'' button, a new properties dialog is systematically displayed.
+* A new ''"Edit"'' button has been added to allow user to display properties dialog of the selected element in the widget.
+* ''Up/Down (Move)'', ''Add'', ''Remove'' and ''Edit' buttons can be visible or grayed out under certain conditions.
+* Some design evolutions (size of the element list is adapted to the number of buttons displayed...).
+
+[[File:../../../image/dev/papyrusReferenceWidget.png]]
+
+[[File:../../../image/dev/papyrusReferenceWidget_PropertiesView.png]]
+
+This "Papyrus Reference" advanced widget has several properties used to configure its behavior.
+These properties are the same as the existing reference widget (see documentation Sirius > Sirius Specifier Manual > Properties View>Properties View description > Reference).
diff --git a/plugins/doc/org.eclipse.papyrus.sirius.doc/src/site/mediawiki/papyrus-sirius-userDoc.mediawiki b/plugins/doc/org.eclipse.papyrus.sirius.doc/src/site/mediawiki/papyrus-sirius-userDoc.mediawiki
index 270d832d4..9f83abb18 100755
--- a/plugins/doc/org.eclipse.papyrus.sirius.doc/src/site/mediawiki/papyrus-sirius-userDoc.mediawiki
+++ b/plugins/doc/org.eclipse.papyrus.sirius.doc/src/site/mediawiki/papyrus-sirius-userDoc.mediawiki
@@ -139,3 +139,72 @@ This tab is also displayed in properties view when an element is selected in a S
 In case of properties view displayed on element from Sirius representation, user can hide this tab by unchecking preference ''Show semantic tab'' from Sirius preferences (''Sirius>Sirius Properties view'').
 
 [[File:../../../image/user/semanticTabPreference.png|500px]]
+
+==Custom widgets==
+
+In the properties view, there are various types of widgets to manipulate and display values of semantic elements: text widgets, checkboxes, combo boxes, radio buttons, ...
+
+Some of Sirius specifiers need to build custom or complex Properties view to match their designers and their needs.
+These new Properties View are defined with advanced controls described in the following parts.
+
+===Papyrus Reference widget===
+
+A new Papyrus Reference Widgets is available specifically to handle various relations between elements of the UML model.
+The reference widget is used to edit four kind of references:
+
+* Multi-valued references with containment.
+* Multi-valued references without containment.
+* Mono-valued references with containment.
+* Mono-valued references without containment.
+
+=====Multi-valued references with containment=====
+Multi-valued references with containment are represented by a widget with a table that contains the list of elements of the relation and some buttons to manage the reference.
+
+[[File:../../../image/user/multi-valuedReferenceWithContainment_example.png]]
+
+The user can double-click on each element of the list to display properties of this element in a new properties dialog.
+Several buttons are displayed in column on the right side of the list :
+
+* '''Up and Down''' buttons : they allow to change the order of the list by moving the selected elements. These buttons do not appear if the reference is not ordered. If no element is selected in the list, these buttons are grayed.
+* '''Add''' button : it allows to create a new element in the list. It is grayed if the list contains the maximum number of items allowed by the reference.
+** After clicking on the button, if the type of the element is simple (only one type can be contained by the reference), a properties dialog is displayed. This dialog allows to fill all the fields of the object to create.
+*** [[File:../../../image/user/addButtonDialog.png]]
+** If the type of the element is complex (several types can be contained by the reference), a wizard is invoked before the display of the properties dialog. This wizard allow the user to choose the type of the object he wants to create.
+*** [[File:../../../image/user/addWizardDialog.png]]
+
+* '''Remove''' button : it removes the selected element from the reference. If none element is selected in the list, this button is grayed.
+* '''Edit''' button : it displays the properties dialog used to edit values of the selected element. If none element is selected in the list, this button is grayed.
+
+[[File:../../../image/user/editButtonDialog.png]]
+
+=====Multi-valued references without containment=====
+Multi-valued references without containment are represented by the same widget, but with the ''Browse'' button in addition and a different behavior on the ''Add'' button.
+
+[[File:../../../image/user/multi-valuedReferenceWithoutContainment_example.png]]
+
+* '''Browse''' button : it allows the user to select an element in the model to add to the reference. If no element is selected in the list, this button is grayed.
+
+[[File:../../../image/user/browseButtonMultiRefWithoutContainment.png]]
+
+* '''Add''' button : it still allows to create a new element in the list but a wizard is invoked each time you click on the button before displaying properties dialog. This wizard allows the user to choose the container of the new object, the reference used to contain this element and its type.
+
+[[File:../../../image/user/addButtonMultiRefWithoutContainment.png]]
+
+=====Mono-valued references with containment=====
+Mono-valued references with containment are represented by a widget with one element and some buttons to manage the reference.
+
+[[File:../../../image/user/mono-valuedReferenceWithContainment_example.png]]
+
+User can double-click on the element to display properties of this element in a new properties dialog.
+Several buttons are displayed horizontally on the right side of the element :
+
+* '''Add''' button : the behavior is the same as that of the Multi-valued references with containment.
+* '''Edit''' button : the behavior is the same as that of the Multi-valued references with containment.
+* '''Remove''' button : it removes the element targeted by the reference. Note that this button may be not available if the reference is required or is a container.
+
+=====Mono-valued references without containment=====
+Mono-valued references without containment are represented by the same widget as above, but with the ''Browse'' button in addition.
+
+[[File:../../../image/user/mono-valuedReferenceWithoutContainment_example.png]]
+
+* '''Browse''' button : it invokes the same Dialog as the ''Browse'' button for Multi-valued references without containment.