NPAL14167: Update documentation.

doc/salome/gui/GEOM/input/creating_compound.doc

@@ -10,6 +10,8 @@ Entity - > Build - > Compound</b>.
 
 \n <b>TUI Command:</b> <em>geompy.MakeCompound(ListOfShape)</em>
 \n <b>Arguments:</b> Name + List of shapes.
+\n <b>Advanced option:</b>
+   \ref restore_presentation_parameters_page "Set presentation parameters and subshapes from arguments".
 
 \image html neo-obj7.png
 
@@ -20,4 +22,4 @@ Entity - > Build - > Compound</b>.
 Our <b>TUI Scripts</b> provide you with useful examples of creation of 
 \ref tui_creation_compound "Advanced Geometric Objects".
 
-*/
+*/

doc/salome/gui/GEOM/input/restore_presentation_parameters.doc

@@ -0,0 +1,53 @@
+/*!
+
+\page restore_presentation_parameters_page Restore presentation parameters and a tree of subshapes
+
+\n This functionality allows the operation result to inherit colour
+and subshapes from its arguments.
+
+\n To activate this functionality, one should check the "Set
+presentation parameters and subshapes from arguments" checkbox in
+corresponding dialog.
+
+\image html restore-ss-dialog.png
+
+\n Let us view an example to understand, how it works.
+Before the partitioning we had box Box_1 with two published faces and
+cylinder Cylinder_1 with free published edges. After the partition we
+have also resulting object with several subshapes, that corresponds to
+operation arguments and their published subshapes. We performed two
+partitions: Partition_1 result obtained by partitioning two objects
+Box_1 and Cylinder_1 as objects, with no tool, Partiton_2 obtained by
+partitioning Box_1 object with Cylinder_1 tool:
+
+\image html restore-ss-OB.png
+
+\n If all the shapes and subshapes have their own colours before the
+partitioning, the resultiong shape and its automatically generated
+subshapes will inherit these colours.
+
+\n If the resulting shape corresponds to its first argument (like
+after transformation or after the boolean operation Cut, or after the
+partiton with one object shape), it inherits its colour, and also
+inherits its subshapes (like Partition_2).
+
+\n In the case, when the resulting shape composed from multiple arguments
+(like after boolean operations, except Cut, or after the partition with
+several object shapes, or it is a compound), it will have default
+colour, but its generated subshapes, corresponding to arguments and
+their subshapes, will inherit corresponding colours. And in this case
+it will have generated subshapes, corresponding to the arguments (like
+Partition_1).
+
+\n See the picture before the partition:
+
+\image html restore-ss-viewer-before.png
+
+\n And the picture, displaying only the Partition_2 with subshapes:
+
+\image html restore-ss-viewer-after.png
+
+\n You can also call this functionality from your python scripts.
+See our <b>TUI Scripts</b> for \ref tui_restore_prs_params "example".
+
+*/

doc/salome/gui/GEOM/input/tui_basic_operations.doc

@@ -79,4 +79,62 @@ gg.createAndDisplayGO(id_archimede)
 gg.setDisplayMode(id_archimede,1) 
 \endcode
 
-*/
+\anchor tui_restore_prs_params
+<br><h2>Restore presentation parameters and subshapes</h2>
+
+\code
+import geompy
+import GEOM
+
+# create a box and a cylinder
+box = geompy.MakeBoxDXDYDZ(200, 200, 200)
+cyl = geompy.MakeCylinderRH(100, 300)
+
+# create translated box
+vec = geompy.MakeVectorDXDYDZ(100, 50, 0)
+tra = geompy.MakeTranslationVector(box, vec)
+
+# create partition objects
+partition1 = geompy.MakePartition([box, cyl])
+partition2 = geompy.MakePartition([box], [cyl])
+partition3 = geompy.MakePartition([box], [tra])
+
+# set colours
+box.SetColor(SALOMEDS.Color(1,0,0))
+cyl.SetColor(SALOMEDS.Color(0,1,0))
+
+# add objects in the study
+geompy.addToStudy(box, "Box")
+geompy.addToStudy(cyl, "Cylinder")
+geompy.addToStudy(vec, "Vector")
+geompy.addToStudy(tra, "Translation")
+geompy.addToStudy(partition1, "Partition_1")
+geompy.addToStudy(partition2, "Partition_2")
+geompy.addToStudy(partition3, "Partition_3")
+
+# Restore presentation parameters and subshapes
+# different methods can be used to find the subshapes in the result:
+# GetInPlace, GetSame, GetInPlaceByHistory, GetShapesOnShape.
+# By default, GetInPlace method is used (GEOM.FSM_GetInPlace)
+geompy.RestoreSubShapes(partition1)
+
+geompy.RestoreSubShapes(partition2, [], GEOM.FSM_GetInPlace)
+
+# The list of arguments can be used to avoid restoring all arguments,
+# but restore only the passed.
+geompy.RestoreSubShapes(partition3, [tra], GEOM.FSM_GetInPlaceByHistory)
+
+# To find subshapes in a transformed shape only one method could be
+# used: pass GEOM.FSM_Transformed for that.
+# True passed for the last argument, means that the transformed shape
+# will inherit colour and subshapes from its first argument (see above
+# MakeTranslation).
+geompy.RestoreSubShapes(tra, [], GEOM.FSM_Transformed, True)
+
+# Also we could do this directly with method addToStudy:
+partition4 = geompy.MakePartition([box, tra])
+geompy.addToStudy(partition4, "Partition_4", True, [],
+                  GEOM.FSM_GetInPlaceByHistory, False)
+\endcode
+
+*/