Coding - Modernize handle APIs and deprecate out-parameter overloads (#1185)

Introduce return-by-value APIs for handle-returning methods across touched toolkits, with nodiscard where appropriate, and keep legacy out-parameter signatures as deprecated wrappers for source compatibility. - Add new return-by-value overloads for previously output-parameter methods in key classes across ApplicationFramework, DataExchange, ModelingAlgorithms, ModelingData, and Visualization - Mark legacy output-parameter methods as deprecated and route them through the new overloads - Update call sites to use the new APIs and simplify temporary-variable patterns - Extend method documentation in OCCT Doxygen style with param/return sections and deprecation guidance - Apply const-correctness updates for read-only handle arguments in STEP reader related interfaces - Preserve compatibility for deprecated public wrappers by keeping exported out-of-line definitions where needed - Perform minor cleanup of comments and parameter naming consistency No functional behavior change is intended; this is an API modernization and migration-facilitation update.
2026-06-14 11:37:02 +08:00 · 2026-04-04 12:09:46 +01:00
parent 83929118e7
commit 0f57a42d89
86 changed files with 1094 additions and 368 deletions
--- a/src/Visualization/TKV3d/AIS/AIS_Line.hxx
+++ b/src/Visualization/TKV3d/AIS/AIS_Line.hxx
@@ -46,22 +46,35 @@ public:
  //! Constructs an infinite line.
  const occ::handle<Geom_Line>& Line() const { return myComponent; }

+  //! Returns the starting point of the line set by SetPoints.
+  //! @return handle to the start point
+  const occ::handle<Geom_Point>& StartPoint() const { return myStartPoint; }
+
+  //! Returns the end point of the line set by SetPoints.
+  //! @return handle to the end point
+  const occ::handle<Geom_Point>& EndPoint() const { return myEndPoint; }
+
  //! Returns the starting point thePStart and the end point thePEnd of the line set by SetPoints.
+  //! @deprecated Use StartPoint() and EndPoint() instead.
+  Standard_DEPRECATED("Use StartPoint() and EndPoint() instead")
  void Points(occ::handle<Geom_Point>& thePStart, occ::handle<Geom_Point>& thePEnd) const
  {
-    thePStart = myStartPoint;
-    thePEnd   = myEndPoint;
+    thePStart = StartPoint();
+    thePEnd   = EndPoint();
  }

-  //! instantiates an infinite line.
+  //! Sets the infinite line.
+  //! @param[in] theLine the geometric line
  void SetLine(const occ::handle<Geom_Line>& theLine)
  {
    myComponent     = theLine;
    myLineIsSegment = false;
  }

-  //! Sets the starting point thePStart and ending point thePEnd of the
+  //! Sets the starting point and ending point of the
  //! infinite line to create a finite line segment.
+  //! @param[in] thePStart the starting point
+  //! @param[in] thePEnd the ending point
  void SetPoints(const occ::handle<Geom_Point>& thePStart, const occ::handle<Geom_Point>& thePEnd)
  {
    myStartPoint    = thePStart;
--- a/src/Visualization/TKV3d/Select3D/Select3D_InteriorSensitivePointSet.cxx
+++ b/src/Visualization/TKV3d/Select3D/Select3D_InteriorSensitivePointSet.cxx
@@ -164,11 +164,10 @@ Select3D_InteriorSensitivePointSet::Select3D_InteriorSensitivePointSet(

 // =======================================================================
 // function : GetPoints
-// purpose  : Initializes the given array theHArrayOfPnt by 3d
+// purpose  : Initializes the given array aHArrayOfPnt by 3d
 //            coordinates of vertices of the whole point set
 // =======================================================================
-void Select3D_InteriorSensitivePointSet::GetPoints(
-  occ::handle<NCollection_HArray1<gp_Pnt>>& theHArrayOfPnt)
+occ::handle<NCollection_HArray1<gp_Pnt>> Select3D_InteriorSensitivePointSet::GetPoints() const
 {
  int aSize = 0;
  for (int anIdx = 0; anIdx < myPlanarPolygons.Length(); ++anIdx)
@@ -177,23 +176,28 @@ void Select3D_InteriorSensitivePointSet::GetPoints(
    aSize += aPolygon->NbSubElements();
  }

-  theHArrayOfPnt          = new NCollection_HArray1<gp_Pnt>(1, aSize);
-  int anOutputPntArrayIdx = 1;
+  occ::handle<NCollection_HArray1<gp_Pnt>> aHArrayOfPnt = new NCollection_HArray1<gp_Pnt>(1, aSize);
+  int                                      anOutputPntArrayIdx = 1;

  for (int aPolygIdx = 0; aPolygIdx < myPlanarPolygons.Length(); ++aPolygIdx)
  {
-    const occ::handle<Select3D_SensitivePoly>& aPolygon = myPlanarPolygons.Value(aPolygIdx);
-    occ::handle<NCollection_HArray1<gp_Pnt>>   aPoints;
-    aPolygon->Points3D(aPoints);
-    int anUpper =
+    const occ::handle<Select3D_SensitivePoly>&     aPolygon = myPlanarPolygons.Value(aPolygIdx);
+    const occ::handle<NCollection_HArray1<gp_Pnt>> aPoints  = aPolygon->Points3D();
+    int                                            anUpper =
      aPolygIdx < myPlanarPolygons.Length() - 1 ? aPoints->Upper() : aPoints->Upper() + 1;
    for (int aPntIter = 1; aPntIter < anUpper; ++aPntIter)
    {
-      theHArrayOfPnt->SetValue(anOutputPntArrayIdx, aPoints->Value(aPntIter));
+      aHArrayOfPnt->SetValue(anOutputPntArrayIdx, aPoints->Value(aPntIter));
      anOutputPntArrayIdx++;
    }
-    aPoints.Nullify();
  }
+  return aHArrayOfPnt;
+}
+
+void Select3D_InteriorSensitivePointSet::GetPoints(
+  occ::handle<NCollection_HArray1<gp_Pnt>>& aHArrayOfPnt)
+{
+  aHArrayOfPnt = GetPoints();
 }

 //=======================================================================
@@ -249,10 +253,9 @@ bool Select3D_InteriorSensitivePointSet::overlapsElement(
  int                                  theElemIdx,
  bool)
 {
-  int                                        aPolygIdx = myPolygonsIdxs->Value(theElemIdx);
-  const occ::handle<Select3D_SensitivePoly>& aPolygon  = myPlanarPolygons.Value(aPolygIdx);
-  occ::handle<NCollection_HArray1<gp_Pnt>>   aPoints;
-  aPolygon->Points3D(aPoints);
+  int                                            aPolygIdx = myPolygonsIdxs->Value(theElemIdx);
+  const occ::handle<Select3D_SensitivePoly>&     aPolygon  = myPlanarPolygons.Value(aPolygIdx);
+  const occ::handle<NCollection_HArray1<gp_Pnt>> aPoints   = aPolygon->Points3D();
  return theMgr.OverlapsPolygon(aPoints->Array1(), Select3D_TOS_INTERIOR, thePickResult);
 }

--- a/src/Visualization/TKV3d/Select3D/Select3D_InteriorSensitivePointSet.hxx
+++ b/src/Visualization/TKV3d/Select3D/Select3D_InteriorSensitivePointSet.hxx
@@ -32,8 +32,14 @@ public:
    const occ::handle<SelectMgr_EntityOwner>& theOwnerId,
    const NCollection_Array1<gp_Pnt>&         thePoints);

+  //! Returns 3d coordinates of vertices of the whole point set.
+  //! @return handle to array of 3D vertex coordinates
+  [[nodiscard]] Standard_EXPORT occ::handle<NCollection_HArray1<gp_Pnt>> GetPoints() const;
+
  //! Initializes the given array theHArrayOfPnt by 3d coordinates of vertices of the
  //! whole point set
+  //! @deprecated Use GetPoints() returning handle by value instead.
+  Standard_DEPRECATED("Use GetPoints() returning handle by value instead")
  Standard_EXPORT virtual void GetPoints(occ::handle<NCollection_HArray1<gp_Pnt>>& theHArrayOfPnt);

  //! Returns the length of vector of planar convex polygons
--- a/src/Visualization/TKV3d/Select3D/Select3D_SensitiveFace.cxx
+++ b/src/Visualization/TKV3d/Select3D/Select3D_SensitiveFace.cxx
@@ -64,16 +64,19 @@ Select3D_SensitiveFace::Select3D_SensitiveFace(
 // purpose  : Initializes the given array theHArrayOfPnt by 3d
 //            coordinates of vertices of the face
 //=======================================================================
-void Select3D_SensitiveFace::GetPoints(occ::handle<NCollection_HArray1<gp_Pnt>>& theHArrayOfPnt)
+occ::handle<NCollection_HArray1<gp_Pnt>> Select3D_SensitiveFace::GetPoints() const
 {
  if (myFacePoints->IsKind(STANDARD_TYPE(Select3D_SensitivePoly)))
  {
-    occ::down_cast<Select3D_SensitivePoly>(myFacePoints)->Points3D(theHArrayOfPnt);
-  }
-  else
-  {
-    occ::down_cast<Select3D_InteriorSensitivePointSet>(myFacePoints)->GetPoints(theHArrayOfPnt);
+    return occ::down_cast<Select3D_SensitivePoly>(myFacePoints)->Points3D();
  }
+
+  return occ::down_cast<Select3D_InteriorSensitivePointSet>(myFacePoints)->GetPoints();
+}
+
+void Select3D_SensitiveFace::GetPoints(occ::handle<NCollection_HArray1<gp_Pnt>>& theHArrayOfPnt)
+{
+  theHArrayOfPnt = GetPoints();
 }

 //=================================================================================================
@@ -98,8 +101,7 @@ bool Select3D_SensitiveFace::Matches(SelectBasics_SelectingVolumeManager& theMgr
 occ::handle<Select3D_SensitiveEntity> Select3D_SensitiveFace::GetConnected()
 {
  // Create a copy of this
-  occ::handle<NCollection_HArray1<gp_Pnt>> aPoints;
-  GetPoints(aPoints);
+  const occ::handle<NCollection_HArray1<gp_Pnt>> aPoints = GetPoints();

  occ::handle<Select3D_SensitiveEntity> aNewEntity =
    new Select3D_SensitiveFace(myOwnerId, aPoints, mySensType);
--- a/src/Visualization/TKV3d/Select3D/Select3D_SensitiveFace.hxx
+++ b/src/Visualization/TKV3d/Select3D/Select3D_SensitiveFace.hxx
@@ -47,8 +47,14 @@ public:
                                         const occ::handle<NCollection_HArray1<gp_Pnt>>& thePoints,
                                         const Select3D_TypeOfSensitivity                theType);

+  //! Returns 3d coordinates of vertices of the face.
+  //! @return handle to array of 3D vertex coordinates
+  [[nodiscard]] Standard_EXPORT occ::handle<NCollection_HArray1<gp_Pnt>> GetPoints() const;
+
  //! Initializes the given array theHArrayOfPnt by 3d
  //! coordinates of vertices of the face
+  //! @deprecated Use GetPoints() returning handle by value instead.
+  Standard_DEPRECATED("Use GetPoints() returning handle by value instead")
  Standard_EXPORT void GetPoints(occ::handle<NCollection_HArray1<gp_Pnt>>& theHArrayOfPnt);

  //! Checks whether the face overlaps current selecting volume
--- a/src/Visualization/TKV3d/Select3D/Select3D_SensitivePoly.cxx
+++ b/src/Visualization/TKV3d/Select3D/Select3D_SensitivePoly.cxx
@@ -235,8 +235,7 @@ bool Select3D_SensitivePoly::Matches(SelectBasics_SelectingVolumeManager& theMgr
  }
  else if (mySensType == Select3D_TOS_INTERIOR)
  {
-    occ::handle<NCollection_HArray1<gp_Pnt>> anArrayOfPnt;
-    Points3D(anArrayOfPnt);
+    const occ::handle<NCollection_HArray1<gp_Pnt>> anArrayOfPnt = Points3D();
    if (!theMgr.IsOverlapAllowed())
    {
      if (theMgr.GetActiveSelectionType() == SelectMgr_SelectionType_Polyline)
--- a/src/Visualization/TKV3d/Select3D/Select3D_SensitivePoly.hxx
+++ b/src/Visualization/TKV3d/Select3D/Select3D_SensitivePoly.hxx
@@ -73,14 +73,25 @@ public:
  Standard_EXPORT int NbSubElements() const override;

  //! Returns the 3D points of the array used at construction time.
-  void Points3D(occ::handle<NCollection_HArray1<gp_Pnt>>& theHArrayOfPnt)
+  //! @return handle to array of 3D points
+  [[nodiscard]] occ::handle<NCollection_HArray1<gp_Pnt>> Points3D() const
  {
-    int aSize      = myPolyg.Size();
-    theHArrayOfPnt = new NCollection_HArray1<gp_Pnt>(1, aSize);
+    int                                      aSize = myPolyg.Size();
+    occ::handle<NCollection_HArray1<gp_Pnt>> aHArrayOfPnt =
+      new NCollection_HArray1<gp_Pnt>(1, aSize);
    for (int anIndex = 1; anIndex <= aSize; anIndex++)
    {
-      theHArrayOfPnt->SetValue(anIndex, myPolyg.Pnt(anIndex - 1));
+      aHArrayOfPnt->SetValue(anIndex, myPolyg.Pnt(anIndex - 1));
    }
+    return aHArrayOfPnt;
+  }
+
+  //! Returns the 3D points of the array used at construction time via output parameter.
+  //! @deprecated Use Points3D() returning handle by value instead.
+  Standard_DEPRECATED("Use Points3D() returning handle by value instead")
+  void Points3D(occ::handle<NCollection_HArray1<gp_Pnt>>& aHArrayOfPnt)
+  {
+    aHArrayOfPnt = Points3D();
  }

  //! Return array bounds.
--- a/src/Visualization/TKV3d/SelectMgr/SelectMgr.cxx
+++ b/src/Visualization/TKV3d/SelectMgr/SelectMgr.cxx
@@ -220,9 +220,8 @@ void SelectMgr::ComputeSensitivePrs(const occ::handle<Graphic3d_Structure>&
    else if (occ::handle<Select3D_SensitiveFace> aFace =
               occ::down_cast<Select3D_SensitiveFace>(anEnt))
    {
-      occ::handle<NCollection_HArray1<gp_Pnt>> aSensPnts;
-      aFace->GetPoints(aSensPnts);
-      occ::handle<NCollection_HSequence<gp_Pnt>> aPoints = new NCollection_HSequence<gp_Pnt>();
+      const occ::handle<NCollection_HArray1<gp_Pnt>> aSensPnts = aFace->GetPoints();
+      occ::handle<NCollection_HSequence<gp_Pnt>>     aPoints = new NCollection_HSequence<gp_Pnt>();
      for (NCollection_HArray1<gp_Pnt>::Iterator aPntIter(*aSensPnts); aPntIter.More();
           aPntIter.Next())
      {