From 858b88250eb0c8edcab15354c87626de08ece957 Mon Sep 17 00:00:00 2001
From: vsv <vsv@opencascade.com>
Date: Fri, 23 Aug 2019 18:18:03 +0300
Subject: [PATCH] Issue #2957: Provide help page for Selection by filters

---
 src/CollectionPlugin/doc/groupFeature.rst     |  37 +----
 src/Config/Config_FeatureReader.cpp           |   8 +-
 src/Config/plugins.xml.in                     |   2 +-
 src/FiltersPlugin/CMakeLists.txt              |   6 +-
 src/FiltersPlugin/doc/FiltersPlugin.rst       | 138 ++++++++++++++++++
 .../doc/images/add.png                        | Bin
 .../doc/images/delete.png                     | Bin
 .../doc/images/reverce.png                    | Bin
 .../doc/images/selection_by_filters.png       | Bin
 .../doc/images/selection_by_filters_added.png | Bin
 src/FiltersPlugin/plugin-Filters.xml          |   3 +-
 11 files changed, 152 insertions(+), 42 deletions(-)
 create mode 100644 src/FiltersPlugin/doc/FiltersPlugin.rst
 rename src/{CollectionPlugin => FiltersPlugin}/doc/images/add.png (100%)
 rename src/{CollectionPlugin => FiltersPlugin}/doc/images/delete.png (100%)
 rename src/{CollectionPlugin => FiltersPlugin}/doc/images/reverce.png (100%)
 rename src/{CollectionPlugin => FiltersPlugin}/doc/images/selection_by_filters.png (100%)
 rename src/{CollectionPlugin => FiltersPlugin}/doc/images/selection_by_filters_added.png (100%)

diff --git a/src/CollectionPlugin/doc/groupFeature.rst b/src/CollectionPlugin/doc/groupFeature.rst
index 1522bf7e0..436653e02 100644
--- a/src/CollectionPlugin/doc/groupFeature.rst
+++ b/src/CollectionPlugin/doc/groupFeature.rst
@@ -3,6 +3,8 @@
 .. |minus.icon|  image:: images/reverce.png
 .. |delete.icon|  image:: images/delete.png
 
+.. _groupPage:
+
 Group
 =====
 
@@ -43,45 +45,12 @@ Input fields:
  
 - The list of selected entities of the given type.  Multiple selection can be done manually in OCC 3D Viewer by mouse click with Shift button pressed or by rectangle selection. To delete entities from the list, select them and call pop-up menu *Delete* item.
 
-- **Selection by filters** button opens "selection by filters" property panel and allows to select entities by set of selected filters.
+- **Selection by filters** button opens "selection by filters" property panel and allows to select entities by set of selected filters. For details on filters see :ref:`filtersPlugin`
 
 - **Show only** button allows to hide all other objects and shapes and show only selected ones.
 
 - Control **Add elements that share the same topology** allows to add automatically all elements laying on the same topology that was selected and remove these elements if they have disappeared due to the parametrical update. They will be represented as one line in the list of selection and managed in the viewer as one object if this flag is enabled. If flag becomes disabled when such elements are already in the list, they will become divided in one line per one shape.
 
-**Selection by filters**
-
-If user presses this button then following property panel appears.
-
-.. image:: images/selection_by_filters.png
-  :align: center
-
-.. centered::
-  Selection by filters property panel
-
-In this panel:
-
-- **Filters** a panel for added filters.
-
-- **Add new filter** combo box. It contains accessible filters according to the selection mode defined in **Group** property panel. When user selects an item from this combo box a filter item appears in **Filters** panel like in the following example:
-
-.. image:: images/selection_by_filters_added.png
-  :align: center
-
-.. centered::
-  Filters **Horizontal faces** and **On plane** added to the property panel.
-  
-Each filter item can be deleted with help of |delete.icon| button. A filter can be reverced with help of toggle button |plus.icon|/|minus.icon|. Also a filter could have input fields in case
-if the filter has arguments.
-
-- **Select** button traverces all objects of a current document and selects entities acceptable by currently defined set of filters. All selected entities will be shown in viewer 3d with
-blue semi-transparent color. Any modification in filters clears current selection.
-
-- **Number of selected objects** shows number currently selected entities.
-
-- **Show only** check box lets to hide all non-selected objects.
-
-**Accept** button in the **Selection by filters** property panel reopens **Group** property panel again and transfers all selected entities to the corresponded list.
 
 **TUI Command**:
 
diff --git a/src/Config/Config_FeatureReader.cpp b/src/Config/Config_FeatureReader.cpp
index 16da267c6..072e61c01 100644
--- a/src/Config/Config_FeatureReader.cpp
+++ b/src/Config/Config_FeatureReader.cpp
@@ -174,6 +174,11 @@ void Config_FeatureReader::fillFeature(xmlNodePtr theFeatureNode,
 
   bool isInternal = getBooleanAttribute(theFeatureNode, ATTR_INTERNAL, false);
   outFeatureMessage->setInternal(isInternal);
+
+  std::string aHelpFile = getProperty(theFeatureNode, HELP_FILE);
+  if (!aHelpFile.empty())
+    outFeatureMessage->setHelpFileName(myLibraryName + "/" + aHelpFile);
+
   if (isInternal) {
     //Internal feature has no visual representation.
     return;
@@ -188,9 +193,6 @@ void Config_FeatureReader::fillFeature(xmlNodePtr theFeatureNode,
   //outFeatureMessage->setTooltip(aToolTip);
   outFeatureMessage->setIcon(getProperty(theFeatureNode, FEATURE_ICON));
   outFeatureMessage->setKeysequence(getProperty(theFeatureNode, FEATURE_KEYSEQUENCE));
-  std::string aHelpFile = getProperty(theFeatureNode, HELP_FILE);
-  if (!aHelpFile.empty())
-    outFeatureMessage->setHelpFileName(myLibraryName + "/" + aHelpFile);
 
   std::string aGroupName = restoreAttribute(NODE_GROUP, _ID);
   std::string aWBNName = restoreAttribute(NODE_WORKBENCH, _ID);
diff --git a/src/Config/plugins.xml.in b/src/Config/plugins.xml.in
index 87476727f..77c60c23c 100644
--- a/src/Config/plugins.xml.in
+++ b/src/Config/plugins.xml.in
@@ -19,7 +19,7 @@
 @ALL_SOLVERS@
 -->
   <plugin library="GeomValidators"/>
-  <plugin library="Filters" configuration="plugin-Filters.xml"/>
+  <plugin library="FiltersPlugin" configuration="plugin-Filters.xml"/>
   <plugin library="DFBrowser" internal="true"/>
 <!--
   <plugin library="SamplePanelPlugin" configuration="plugin-SamplePanel.xml"/>
diff --git a/src/FiltersPlugin/CMakeLists.txt b/src/FiltersPlugin/CMakeLists.txt
index 8cabb8606..2c856188d 100644
--- a/src/FiltersPlugin/CMakeLists.txt
+++ b/src/FiltersPlugin/CMakeLists.txt
@@ -79,8 +79,8 @@ SET(XML_RESOURCES
 )
 
 ADD_DEFINITIONS(-DFILTERS_EXPORTS ${OpenCASCADE_DEFINITIONS})
-ADD_LIBRARY(Filters SHARED ${PROJECT_SOURCES} ${PROJECT_HEADERS} ${XML_RESOURCES})
-TARGET_LINK_LIBRARIES(Filters ${PROJECT_LIBRARIES})
+ADD_LIBRARY(FiltersPlugin SHARED ${PROJECT_SOURCES} ${PROJECT_HEADERS} ${XML_RESOURCES})
+TARGET_LINK_LIBRARIES(FiltersPlugin ${PROJECT_LIBRARIES})
 
 INCLUDE_DIRECTORIES(
   ${OpenCASCADE_INCLUDE_DIR}
@@ -94,7 +94,7 @@ INCLUDE_DIRECTORIES(
   ${PROJECT_SOURCE_DIR}/src/CollectionPlugin
 )
 
-INSTALL(TARGETS Filters DESTINATION ${SHAPER_INSTALL_PLUGIN_FILES})
+INSTALL(TARGETS FiltersPlugin DESTINATION ${SHAPER_INSTALL_PLUGIN_FILES})
 INSTALL(FILES ${XML_RESOURCES} DESTINATION ${SHAPER_INSTALL_XML_RESOURCES})
 INSTALL(FILES ${PROJECT_PYFILES} DESTINATION ${SHAPER_INSTALL_ADDONS})
 
diff --git a/src/FiltersPlugin/doc/FiltersPlugin.rst b/src/FiltersPlugin/doc/FiltersPlugin.rst
new file mode 100644
index 000000000..8e6d0babd
--- /dev/null
+++ b/src/FiltersPlugin/doc/FiltersPlugin.rst
@@ -0,0 +1,138 @@
+.. |plus.icon|  image:: images/add.png
+.. |minus.icon|  image:: images/reverce.png
+.. |delete.icon|  image:: images/delete.png
+
+
+.. _filtersPlugin:
+
+Filters Plugin
+==============
+
+Filters plug-in provides a collection of filters used Filters property panel (for example see :ref:`groupPage` feature).
+
+
+**Selection filters**
+
+Selection by filters panel looks like following:
+
+.. image:: images/selection_by_filters.png
+  :align: center
+
+.. centered::
+  Selection by filters property panel
+
+In this panel:
+
+- **Filters** a panel for added filters.
+
+- **Add new filter** combo box. It contains accessible filters according to the selection mode. When user selects an item from this combo box a filter item appears in **Filters** panel like in the following example:
+
+.. image:: images/selection_by_filters_added.png
+  :align: center
+
+.. centered::
+  Filters **Horizontal faces** and **On plane** added to the property panel.
+  
+Each filter item can be deleted with help of |delete.icon| button. A filter can be reverced with help of toggle button |plus.icon|/|minus.icon|. Also a filter could have input fields in case
+if the filter has arguments.
+
+- **Select** button traverces all objects of a current document and selects entities acceptable by currently defined set of filters. All selected entities will be shown in viewer 3d with
+blue semi-transparent color. Any modification in filters clears current selection.
+
+- **Number of selected objects** shows number currently selected entities.
+
+- **Show only** check box hides all non-selected objects.
+
+**Accept** button in the **Selection filters** property panel reopens a property panel where the **selection filters** was called and transfers all selected entities to the corresponded list.
+
+
+Filters
+-------
+
+**Belongs to**
+
+By default, the result of Selection feature all selectable entities from all Shapes registered in the “Results” folder. This filter provides a way to explicit (restrict) the results in which looking for selectable entities.
+
+- **Result type:** Any
+- **Argument:** Any result object, multiple OR selection accepted
+- **Algorithm:** Returns only shapes that belong to selected results.
+
+**On a plane**
+
+- **Result type:** Vertex, Edge, Face
+- **Argument:** Planar face or Construction plane, multiple OR selection accepted
+- **Algorithm:** Returns all vertices, edges or planar faces geometrically located on (co-planar) the given plane.
+
+**On a Line**
+
+- **Result type:** Vertex, Edge
+- **Argument:** Straight Edge or Construction axis, multiple OR selection accepted
+- **Algorithm:** Returns all vertices coincident or all edges collinear to the given line.
+
+**On geometry**
+
+- **Result type:** Any
+- **Argument:** Any Shape, multiple OR selection accepted
+- **Algorithm:** Returns the shapes which have the similar underlying geometry of the given Shape. Like all faces laying of the same geometrical surface or edges laying of the same geometrical surface or edges laying on the line.
+
+**On plane side**
+
+- **Result type:** Any
+- **Argument:** Planar face or Construction plane
+- **Algorithm:** By default, the side is in direction of normal of the given plane. For getting the other side, simply invert the filter by clicking on the Check button.
+
+**Opposite to an edge**
+
+This algorithm is based on the Propagate geompy function. It works on a model partitioned into quadrangular faces blocks for the purpose of hexahedral meshing.
+
+- **Result type:** Edge
+- **Argument:** An edge belonging to a quadrangular face
+- **Algorithm:** Returns all Edges opposite to the given Edge on all quadrangular faces connected to this Edge. The algorithm is recursive: after an edge is found on one face, it adds edges opposite to this new one.
+
+**On/In/Out a Solid**
+
+This algorithm reproduces the GetShapesOnShape function of geompy.
+
+- **Result type:** Vertex, Edge or Face
+- **Arguments:** Solid. Location according to the given Solid, as described below
+- **Algorithm:**
+    - **In:** strictly inside the solid. 
+    - **Not In:** strictly outside the solid. 
+    - **On:** confused with the boundary of the solid
+    - **Not On:** strictly inside or outside the solid
+    - **In & On:** i.e. inside or confused with the boundary of the solid
+    - **Not In & On:** outside or confused with the boundary of the solid.
+
+**External Faces**
+
+This algorithm finds all not-shared faces.
+
+- **Result type:** Face
+- **Arguments:** None
+- **Algorithm:** Returns all faces which are not shared between higher level shapes of the connected compound of the connected compound of compsolid. For an example, if there is a compsolid of two boxes with one shared face between them, the filter returns all faces except the shared.
+
+**Horizontal Faces**
+
+This algorithm finds all the horizontal faces of the model.
+
+- **Result type:** Face
+- **Arguments:** None
+- **Algorithm:** Returns only planar faces with normal of the plane perpendicular to OZ.
+
+**Vertical Faces**
+
+This algorithm finds all the vertical faces of the model.
+
+- **Result type:** Face
+- **Arguments:** None
+- **Algorithm:** Returns only planar faces with normal of the plane parallel to OZ or cylindrical faces with axis parallel to OZ.
+
+**Topologically connected Faces**
+
+This algorithm finds all the faces topologically connected the argument selected by the user.
+
+- **Result type:** Face
+- **Arguments:** A point, an edge or a face. A “propagation” flag (check-box).
+- **Algorithm:**
+    - If a point of an edge is selected as an argument, the result is all faces that contain this argument.If a face is selected, the result is all faces that have shared edges or vertices with this selection.
+    - If “propagation” flag is enabled (it is disabled by default), the algorithm becomes recursive: all connected faces are added to the results. So, for the solid shape there will be all faces except internal-volumes faces, not connected to any external faces.
\ No newline at end of file
diff --git a/src/CollectionPlugin/doc/images/add.png b/src/FiltersPlugin/doc/images/add.png
similarity index 100%
rename from src/CollectionPlugin/doc/images/add.png
rename to src/FiltersPlugin/doc/images/add.png
diff --git a/src/CollectionPlugin/doc/images/delete.png b/src/FiltersPlugin/doc/images/delete.png
similarity index 100%
rename from src/CollectionPlugin/doc/images/delete.png
rename to src/FiltersPlugin/doc/images/delete.png
diff --git a/src/CollectionPlugin/doc/images/reverce.png b/src/FiltersPlugin/doc/images/reverce.png
similarity index 100%
rename from src/CollectionPlugin/doc/images/reverce.png
rename to src/FiltersPlugin/doc/images/reverce.png
diff --git a/src/CollectionPlugin/doc/images/selection_by_filters.png b/src/FiltersPlugin/doc/images/selection_by_filters.png
similarity index 100%
rename from src/CollectionPlugin/doc/images/selection_by_filters.png
rename to src/FiltersPlugin/doc/images/selection_by_filters.png
diff --git a/src/CollectionPlugin/doc/images/selection_by_filters_added.png b/src/FiltersPlugin/doc/images/selection_by_filters_added.png
similarity index 100%
rename from src/CollectionPlugin/doc/images/selection_by_filters_added.png
rename to src/FiltersPlugin/doc/images/selection_by_filters_added.png
diff --git a/src/FiltersPlugin/plugin-Filters.xml b/src/FiltersPlugin/plugin-Filters.xml
index 93d740d68..b1718c025 100644
--- a/src/FiltersPlugin/plugin-Filters.xml
+++ b/src/FiltersPlugin/plugin-Filters.xml
@@ -3,7 +3,8 @@
     <group id="Collections">
       <feature id="FiltersSelection"
                title="Selection filters"
-               internal="1">
+               internal="1"
+               helpfile="FiltersPlugin.html">
         <selection_filters/>
       </feature>
     </group>
-- 
2.39.2