0028786: Refactoring of the Warning/Error reporting system of Boolean Operations...

[occt.git] / dox / user_guides / boolean_operations / boolean_operations.md

diff --git a/dox/user_guides/boolean_operations/boolean_operations.md b/dox/user_guides/boolean_operations/boolean_operations.md
index b224df2..55da9a7 100644 (file)
--- a/dox/user_guides/boolean_operations/boolean_operations.md
+++ b/dox/user_guides/boolean_operations/boolean_operations.md
@@ -2708,6 +2708,58 @@ To enable the safe processing mode for the operation in DRAW, it is necessary to
 bnondestructive 1
 ~~~~
 
+@section occt_algorithms_ers Errors and warnings reporting system
+
+The chapter describes the Error/Warning reporting system of the algorithms in the Boolean Component.
+
+The errors and warnings are collected in the instance of the class *Message_Report* maintained as a field by common base class of Boolean operation algorithms *BOPAlgo_Options*.
+
+The error is reported in for problems which cannot be treated and cause the algorithm to fail. 
+In this case the result of the operation will be incorrect or incomplete or there will be no result at all. 
+
+The warnings are reported for the problems which can be potentially handled or ignored and thus do not cause the algorithms to stop their work (but probably affect the result). 
+
+All possible errors and warnings that can be set by the algorithm are listed in its header file.
+The complete list of errors and warnings that can be generated by Boolean operations is defined in *BOPAlgo_Alerts.hxx*.
+
+Use method *HasErrors()* to check for presence of error; method *HasError()* can be used to check for particular error.
+Methods *DumpErrors()* outputs textual description of collected errors into the stream.
+Similar methods *HasWarnings()*, *HasWarning()*, and *DumpWarnings()* are provided for warnings.
+
+Note that messages corresponding to errors and warnings are defined in resource file *BOPAlgo.msg*.
+These messages can be localized; for that put translated version to separate file and load it in the application by call to *Message_MsgFile::Load()* .
+
+Here is the example of how to use this system:
+~~~~~
+BOPAlgo_PaveFiller aPF;
+aPF.SetArguments(...);
+aPF.Perform();
+if (aPF.HasErrors()) {
+  aPF.DumpErrors(std::cerr);
+  //
+  if (aPF.HasError(STANDARD_TYPE(BOPAlgo_AlertNullInputShapes)) {
+    // some actions
+  }
+  if (aPF.HasWarning(STANDARD_TYPE(BOPAlgo_AlertTooSmallEdge)) {
+    // some actions
+  }
+  ...
+}
+~~~~~
+
+DRAW commands executing Boolean operations output errors and warnings generated by these operations in textual form.
+Additional option allows saving shapes for which warnings have been generated, as DRAW variables. 
+To activate this option, run command *bdrawwarnshapes* with argument 1 (or with 0 to deactivate):
+~~~~
+bdrawwarnshapes 1
+~~~~
+
+After setting this option and running an algorithm the result will look as follows:
+~~~~
+Warning: The interfering vertices of the same argument: ws_1_1 ws_1_2
+Warning: The positioning of the shapes leads to creation of small edges without valid range: ws_2_1
+~~~~
+
 
 @section occt_algorithms_11b Usage