Attaching the Geometric Tolerances
The functions explained in this section enable you to access and set attachment options for the geometric tolerance.
Function Introduced:
• ProGtolAttachGet()
• ProGtolAttachSuppressedLeadersGet()
• ProGtolAttachSet()
• ProGtolAttachTypeGet()
• ProGtolAttachLeadersGet()
• ProGtolAttachLeadersSet()
• ProGtolleaderGet()
• ProGtolleaderZExtensionlineGet()
• ProGtolEnvelopeGetWithFlags()
• ProGtolEnvelopeGet()
• ProGtolleadersFree()
• ProGtolAttachOffsetItemGet()
• ProGtolAttachOffsetItemSet()
• ProGtolAttachFreeGet()
• ProGtolAttachFreeSet()
• ProGtolleaderFree()
• ProGtolAttachOnDatumGet()
• ProGtolAttachOnDatumSet()
• ProGtolAttachOnAnnotationGet()
• ProGtolAttachOnAnnotationSet()
• ProGtolAttachMakeDimGet()
• ProGtolAttachMakeDimSet()
• ProGtolMakeDimensionGet()
• ProLegacyGtolReferenceGet()
The function ProGtolAttachGet() retrieves all the attachment related information for a gtol as a ProGtolAttach structure. Use the function ProGtolAttachSet() to set the attachment options. If the function ProGtolAttachSet() specifies one or more leaders, the leaders are described by a separate opaque object called ProGtolleader. This object is allocated by call to the function ProGtolleaderAlloc(). Use the function ProGtolleaderFree() to free the allocated memory.
The function ProGtolAttachTypeGet() retrieves the type of attachment for a gtol. It uses the enumerated data type ProGtolAttachType to provide information about the placement of the gtol. The valid values are:
• PRO_GTOL_ATTACH_DATUM – Specifies that the gtol is placed on its reference datum.
• PRO_GTOL_ATTACH_ANNOTATION—Specifies that the gtol is attached to an annotation.
• PRO_GTOL_ATTACH_ANNOTATION_ELBOW—Specifies that the gtol is attached to the elbow of an annotation.
• PRO_GTOL_ATTACH_FREE—Specifies that the gtol is placed as a free. It is unattached to the model or drawing.
• PRO_GTOL_ATTACH_LEADERS—Specifies that the gtol is attached with one or more leader to geometry such as, edge, dimension witness line, coordinate system, axis center, axis lines, curves, or surface points, vertices, section entities, draft entities, and so on. The leaders are represented using an opaque handle, ProGtolleader.
• PRO_GTOL_ATTACH_OFFSET—Specifies that the gtol frame can be placed at an offset from the following drawing objects: dimension, dimension arrow, gtol, note, and symbol.
• PRO_GTOL_ATTACH_MAKE_DIM—Specifies that the gtol frame is attached to a dimension line.
Use the function ProGtolAttachLeadersGet() to get attachment details for leader type of gtol. The output arguments are:
• plane—Specifies the annotation plane. For gtols defined in drawing, it returns NULL.
• type—Specifies the attachment type for the leader using the enumerated data type ProGtolLeaderAttachType.
• leaders—Specifies a ProArray of gtol leaders.
• location—Specifies the location of gtol text in model coordinates.
Use the function ProGtolAttachSuppressedLeadersGet() to get the number of leaders that are suppressed due to missing references.
Use the function ProGtolAttachLeadersSet() to set the attachment options for leader type of gtol.
To unpack the information in the ProGtolleader handle, use the function ProGtolleaderGet(). After reading the leaders, free the leader array by calling ProGtolleadersFree().
The function ProGtolleaderZExtensionlineGet() retrieves the Z-Extension line of the gtol leader. The leader location coordinates are required when the gtol is moved to a different annotation plane.
The function ProGtolEnvelopeGetWithFlags() gets the envelope of the gtol. To retrieve coordinates of the gtol in a specified solid, if the gtol is displayed in the solid as well as in the drawing, the drawing must not be active. The input arguments are:
• gtol—The handle to the gtol using the object ProGtol.
• drawing—Specify the drawing using the object ProDrawing. Pass the value only for solid gtol shown in a drawing; otherwise, pass it as NULL.
• flags—Specify the gtol envelope flag using the enumerated data type ProGtolEnvelopeFlag. The value PRO_GTOL_ENVELOPE_SKIP_OUTSIDE_TEXT must be passed to get an envelope without an additional text; otherwise, pass it as PRO_GTOL_ENVELOPE_DEFAULT.
The output argument envelope is the envelope surrounding the gtol in the model coordinate system. For flat-to-screen gtol, the envelope is in screen coordinates. For a drawing, it is in the screen coordinates. For additional texts, there is no padding.
The function ProGtolEnvelopeGet() returns the envelope of the gtol. The output argument envelope is the envelope surrounding the gtol in the coordinate system of the model. For drawing, the envelope of the gtol is in the screen coordinates. While retrieving coordinates of the gtol in a specified solid, if the gtol is displayed in the solid as well as in the drawing, the drawing must not be active.
The function ProGtolAttachOffsetItemGet() returns the offset references for the specified ProGtolAttach structure. The function returns the following output arguments:
• offset_ref—Specifies the offset reference as a ProSelection object. The reference can be a dimension, arrow of a dimension, another geometric tolerance, note, or a symbol instance. If there are no offset references, the output argument returns NULL.
• offset—Specifies the position of the offset reference as model coordinates.
Use the function ProGtolAttachOffsetItemSet() to set the offset references for the specified ProGtolAttach structure.
The function ProGtolAttachFreeGet() gets the details for free type of gtol. It retrieves information about the annotation plane and location of the gtol text in model coordinates. For gtols defined in drawing, the function returns NULL for annotation plane. Use the function ProGtolAttachFreeSet() to set the options for free type gtol.
The functions ProGtolAttachOnDatumGet() and ProGtolAttachOnDatumSet() get and set datum symbol for the geometric tolerance. From 4.0 F000 onward, datum symbols are defined using datum feature symbol. The functions work with the new datum feature symbol along with the legacy datum tag annotations.
The function ProGtolAttachOnAnnotationGet() retrieves the annotation for the specified ProGtolAttach structure. The function ProGtolAttachOnAnnotationSet() sets the specified annotation to the attachment structure. The input arguments are:
• gtol_attach—Specifies the attachment structure ProGtolAttach for a geometric tolerance.
• p_annot—Specifies the annotation. For gtols in the solid you can set PRO_DIMENSION, PRO_GTOL, and PRO_NOTE type of annotations. For drawing gtols, you can set PRO_DIMENSION, PRO_GTOL, and PRO_NOTE type of annotations.
• elbow—Specifies that the annotation must be placed on the elbow of the leader instead of the gtol text. If the annotation type is set as PRO_NOTE, then you must set elbow as PRO_B_TRUE.
The function ProGtolAttachMakeDimGet() gets all the information for a geometric tolerance created with Make Dim type of reference. Make Dim type of reference mode enables you to create a dimension line and place the gtol frame attached to it. The geometric tolerance appears in standard dimension format, but with the geometric tolerance instead of a dimension value. The output arguments are:
• plane—Specifies the annotation plane for the gtol.
• attachments_arr—Specifies the points on the model or drawing where the gtol is attached.
• dsense_arr—Specifies more information about how the gtol attaches to each attachment point of the model or drawing.
• orient_hint—Specifies the orientation of the gtol using the enumerated data type ProDimOrient. The valid values are
◦ PRO_DIM_ORNT_HORIZ—Specifies a horizontal dimension.
◦ PRO_DIM_ORNT_VERT—Specifies a vertical dimension.
◦ PRO_DIM_ORNT_SLANTED—Specifies the shortest distance between two attachment points. This value is available only when the dimension is attached to points.
◦ PRO_DIM_ORNT_ELPS_RAD1—Specifies the start radius for a dimension on an ellipse.
◦ PRO_DIM_ORNT_ELPS_RAD2—Specifies the end radius for a dimension on an ellipse.
◦ PRO_DIM_ORNT_ARC_ANG—Specifies the angle of the arc for a dimension of an arc.
◦ PRO_DIM_ORNT_ARC_LENGTH—Specifies the length of the arc for a dimension of an arc.
◦ PRO_DIM_ORNT_LIN_TANCRV_ANG—If the dimension is attached to a line and an end point of a curve, the default dimension will be a linear dimension showing the distance between the line and the curve point. Set this value if you want the dimension to show instead the angle between the line and the tangent at the curve point.
◦ PRO_DIM_ORNT_RAD_DIFF—Specifies the linear dimension of the radial distance between two concentric arcs or circles.
◦ PRO_DIM_ORNT_NORMAL—Specifies the linear dimension between two points to be placed normal to the selected reference.
◦ PRO_DIM_ORNT_PARALLEL—Specifies the linear dimension between two points to be placed parallel to the selected reference.
• location—Specifies the location of gtol text as model coordinates.
The function ProGtolAttachMakeDimSet() sets all the options to create a geometric tolerance with Make Dim type of reference.
The function ProGtolMakeDimensionGet() gets the dimension of the Make Dim type of reference using a gtol object. The input argument is gtol specifies the valid geometric tolerance.
The output argument dim returns ProDimension of Make Dim gtol.
The function ProLegacyGtolReferenceGet() returns the item that was referenced by a gtol created in releases prior to Creo 4.0. The input argument gtol is the legacy gtol created before Creo 4.0 and not converted. The output arguments are as follows:
• type—The type of item being referenced, which is defined by the enumerated data type ProGtolRefItemType
• reference—ProSelection of item being referenced.