Assembly: Kinematic Dragging and Creating Snapshots
This section describes the Creo Parametric TOOLKIT functions for dragging assembly entities through an allowable range to see how your assembly works in a specific configuration. These functions provide the same result as obtained by using the Drag dialog box in the Creo Parametric user interface.
This chapter also describes the functions to create snapshots of the assembly in different positions and orientations.
Connecting to a Kinematic Drag Session
Functions Introduced:
  • ProKinDragStart()
    		•
  • ProKinDragStop()
    		•
  • ProKinDragSessionInquire()
    		•
  • ProKinDragEnvironmentSet()
    		•
  • ProKinDragReconnect()
    		•
    The function ProKinDragStart() starts a drag session. This function should be called before any other function for Kinematic drag or snapshots. All subsequent functions work with the snapshots of the top-level assembly. This function can be called for design assemblies in the Standard Assembly and Mechanism modes only. It cannot be used in the following cases:
    •  If the assembly is in the exploded state
    •  If the Sketcher mode is active
    •  When component placement is active
    •  When the Drag dialog box is active
    The function ProKinDragStop() stops the drag session. Use ProWindowRefresh() to view the change in the graphic window scale according to the updated outline.
    The function ProKinDragSessionInquire() determines if the drag session is active. The drag session may exist automatically in some cases, such as redefine, regeneration, window switch, representation mode change.
    The function ProKinDragEnvironmentSet() sets the environment for dragging and reconnect operations. It requires the following input arguments:
    •  snap_name—Specifies the name of the active snapshot whose constraints are used for the drag operation. The snapshot is checked for statuses such as good, outdated, or incomplete. Pass NULL if not required.
    The outdated status means some parts from the body have a relative transformation that is different from the current transformation. The incomplete status means that some parts from the body are missing in the active snapshot.
    •  path—Specifies the path in terms of the ProAsmcomppath object to the active snapshot of a subassembly contained within the top-level assembly. Pass NULL for a top-level assembly snapshot.
    •  type—Specifies the type of drag to be performed. It is given by the enumerated type ProKinDragType that takes the following values:
    ○  PRO_KIN_POINT_DRAG— Select a point to drag in a part within the top-level assembly. During the dragging operation, the point you selected follows the pointer’s movement while maintaining connections.
    ○  PRO_KIN_BODY_DRAG—Select a part from the top-level assembly to drag. When you drag a part, its position in the graphics window changes, but its orientation remains fixed.If the assembly requires a part to be reoriented in conjunction with a change in position, the part does not move at all, as the assembly cannot reassemble in the new position.
    ○  PRO_KIN_ADVANCED_TRANS_X—Specifies the translation in the X direction of the selected coordinate system. This type is applicable only in case of an advanced drag operation. You can select a coordinate system by selecting the part to be dragged.
    ○  PRO_KIN_ADVANCED_TRANS_Y—Specifies the translation in the Y direction of the selected coordinate system. This type is applicable only in case of an advanced drag operation.
    ○  PRO_KIN_ADVANCED_TRANS_Z—Specifies the translation in the Z direction of the selected coordinate system. This type is applicable only in case of an advanced drag operation.
    ○  PRO_KIN_ADVANCED_ROT_X—Specifies the rotation around the X axis of the selected coordinate system. This type is applicable only in case of an advanced drag operation. You can select a coordinate system by selecting the part to be dragged.
    ○  PRO_KIN_ADVANCED_ROT_Y—Specifies the rotation around the Y axis of the selected coordinate system. This type is applicable only in case of an advanced drag operation.
    ○  PRO_KIN_ADVANCED_ROT_Z—Specifies the rotation around the Z axis of the selected coordinate system. This type is applicable only in case of an advanced drag operation.
    •  refobject—Specifies the selection reference in the form a coordinate system (PRO_CSYS), part (PRO_PART), or mechanism body (PRO_MDO_BODY) for an advanced drag operation. This argument is relevant only for advanced drag types. For all other drag types, it is ignored and NULL should be passed.
    The function ProKinDragReconnect() reconnects to a drag session taking into account constraints but not transforms from the active snapshot specified in ProKinDragEnvironmentSet(). Use ProWindowRefresh() to view the changes in the positions of the assembly components. Refer to the sections Snapshot Constraints and Snapshot Transforms for more information.
    Performing Kinematic Drag
    Function Introduced:
  • ProKinDragPerformMove()
    		•
    The function ProKinDragPerformMove() drags the selected geometric object to the specified X and Y screen coordinates given by ProArray of Pro2dPnt object. The geometric object can be PRO_POINT, PRO_SURFACE_PNT, PRO_AXIS, PRO_EDGE, PRO_CURVE, PRO_DATUM_PLANE, PRO_SRF_PLANE_PNT, or PRO_SURFACE in case of a point drag, and PRO_PART or PRO_MDO_BODY for all other drag types. A hook point is displayed on the object selected for drag, which is removed at the end of the drag operation. The dragging is performed according to the environment set by the function ProKinDragEnvironmentSet(). Use the constraints set for the active snapshot while dragging.
    Creating and Modifying Snapshots
    Functions Introduced:
  • ProKinDragSnapshotsNamesGet()
    		•
  • ProSnapshotCreate()
    		•
  • ProSnapshotUpdate()
    		•
  • ProSnapshotRename()
    		•
  • ProSnapshotDelete()
    		•
  • ProSnapshotApply()
    		•
    The function ProKinDragSnapshotsNamesGet() retrieves an array of names of the snapshots belonging to the top-level assembly and all its subassemblies.
    The function ProSnapshotCreate() creates a new snapshot for the top-level assembly as per its current position in the Creo Parametric window. Constraints are copied from the active snapshot. The newly created snapshot becomes active.
    The function ProSnapshotUpdate() updates the snapshot for the top-level assembly as per its current position in the Creo Parametric window. Constraints are copied from the active snapshot. The newly updated snapshot becomes active.
    The function ProSnapshotRename() renames the active snapshot of the top-level assembly.
    The function ProSnapshotDelete() deletes a specified snapshot. The snapshot can be of the top-level assembly or any of its subassemblies. Pass NULL for the argument path to specify the top-level assembly.
    The function ProSnapshotApply() applies the transforms of the active snapshot. Unlike in the user interface, no attempt to reconnect is made. Call ProKinDragReconnect() if reconnect is necessary. Use ProWindowRefresh() to view the changes in the positions of the assembly components.
    Snapshot Constraints
    The constraints that can be applied to a snapshot are contained by the structure ProSnapshotConstraint. The declaration for ProSnapshotConstraint is as follows: 
    typedef struct proSnapshotConstraint
{
ProSnapshotConstraintType   type;
ProSelection               *sel_array;
double                      value;
ProBool                     user_active;
ProBool                     valid
} ProSnapshotConstraint;
    The fields in the above structure are described as follows:
    •  type—Specifies the type of snapshot constraint. The type is represented by the enumerated type ProSnapshotConstraintType and can take one of the following values:
    ○  PRO_SNAP_ALIGN—Select two points, two lines, or two planes from the top-level assembly. The two entities remain aligned during the drag operation.
    ○  PRO_SNAP_MATE—Select two planes from the top-level assembly. The planes remain mated during the drag operation.
    ○  PRO_SNAP_ORIENT—Select two planes that orient at an angle with each other.
    ○  PRO_SNAP_MOTION_AXIS_POS—Select a motion axis to specify the motion axis position.
    ○  PRO_SNAP_BODY_LOCK—Select the bodies to be locked together while dragging.
    ○  PRO_SNAP_CONNECTION_DISABLE—Select a connection that will be disabled while dragging.
    ○  PRO_SNAP_PARALLEL_VIEW_PLANE—Select a body that will move parallel only to the view plane. This constraint type is the same as the PRO_SNAP_ALIGN or PRO_SNAP_MATE types, but the second reference in this case is the view plane. This constraint type is available only via Creo Parametric TOOLKIT. If set by the Creo Parametric TOOLKIT application, this constraint type becomes visible in the Drag dialog box in the Creo Parametric user interface, but it cannot be stored.
    ○  PRO_SNAP_CAM_LIFTOFF_ENABLE—Allows two cams with a cam-follower connection to separate and collide during a dragging operation.
    ○  PRO_SNAP_CAM_LIFTOFF_DISABLE—Requires two cams with a cam-follower connection to be in contact with each other during the dragging operation.
    Note
    The constraint types PRO_SNAP_CAM_LIFTOFF_ENABLE and PRO_SNAP_CAM_LIFTOFF_DISABLE override the Enable Liftoff property that you set from the Cam-Follower Connection Definition dialog box in the Creo Parametric user interface.
    •  *sel_array—Specifies the ProArray of selections. The number of selections needed and the permitted selection types for each constraint type are specified in the following table:
    Constraint Type
    Number of Selections needed
    Permitted Selection Types
    PRO_SNAP_ALIGN
    2
    PRO_POINT, PRO_SURFACE_PNT, PRO_AXIS, PRO_EDGE, PRO_CURVE, PRO_DATUM_PLANE, PRO_SRF_PLANE_PNT, PRO_SURFACE
    PRO_SNAP_MATE, PRO_SNAP_ORIENT
    PRO_DATUM_PLANE, PRO_SRF_PLANE_PNT, PRO_SURFACE
    PRO_SNAP_MOTION_AXIS_POS
    1
    PRO_MDO_CONN_AXIS_ROT_1/2/3, PRO_MDO_CONN_AXIS_TR_1/2/3, PRO_MDO_SLOT_AXIS
    PRO_SNAP_CONNECTION_DISABLE
    PRO_MDO_CONN, PRO_MDO_CAM_CONN, PRO_MDO_SLOT_CONN, PRO_MDO_GEAR_CONN
    PRO_SNAP_PARALLEL_VIEW_PLANE
    PRO_POINT, PRO_SURFACE_PNT, PRO_EDGE_START, PRO_EDGE_END, PRO_CRV_START, PRO_CRV_END, PRO_AXIS, PRO_EDGE, PRO_CURVE, PRO_SRF_PLANE_PNT, PRO_SURFACE, PRO_DATUM_PLANE
    PRO_SNAP_CAM_LIFTOFF
    _ENABLE
    PRO_MDO_CAM_CONN
    PRO_SNAP_CAM_LIFTOFF
    _DISABLE
    PRO_SNAP_BODY_LOCK
    2 or more
    PRO_PART, PRO_MDO_BODY
    •  value—Depending upon the constraint type, this field takes the following values:
    ○  For the PRO_SNAP_ALIGN and PRO_SNAP_MATE constraint types, value specifies the linear distance between the references.
    ○  For the PRO_SNAP_ORIENT type, value specifies the angle between the references.
    ○  For the PRO_SNAP_MOTION_AXIS_POS type, value specifies the offset of the joint axis zero position. This value is angular for the rotation axis and linear for the translational axis. The references for the joint axis zero position may be default or as specified by the user.
    •  active—Specifies the ProBoolean option to enable or disable a constraint.
    •  valid—Specifies if the constraint is valid or invalid in the current model context. If this ProBoolean option is PRO_B_TRUE, the constraint is valid (active), and if it is PRO_B_FALSE, the constraint is invalid (suppressed).
    Functions Introduced:
  • ProSnapshotConstraintsGet()
    		•
  • ProSnapshotConstraintAdd()
    		•
  • ProSnapshotConstraintDelete()
    		•
  • ProSnapshotConstraintUpdate()
    		•
  • ProSnapshotConstraintEvaluate()
    		•
    The function ProSnapshotConstraintsGet() retrieves all the constraints of a specified snapshot. The snapshot can be of the top-level assembly or any of its subassemblies. Pass NULL for the argument path to specify the top-level assembly.
    The function ProSnapshotConstraintAdd() adds a constraint to the snapshot of the top-level assembly.
    The function ProSnapshotConstraintDelete() deletes a constraint from the snapshot of the top-level assembly.
    The function ProSnapshotConstraintUpdate() updates a constraint for the snapshot of the top-level assembly.
    The function ProSnapshotConstraintEvaluate() calculates the position of the motion axis for the constraint type PRO_SNAP_MOTION_AXIS_POS for the active model in the Creo Parametric window. This value does not depend on the current snapshot and it is not necessary for the snapshot to contain the constraint.
    Snapshot Transforms
    Functions Introduced:
  • ProSnapshotTrfsGet()
    		•
  • ProSnapshotTrfsUpdate()
    		•
    The function ProSnapshotTrfsGet() retrieves the transformation paths and transformation matrices saved in the snapshots for the subassemblies and their components with respect to the top-level assembly snapshot.
    The function ProSnapshotTrfsUpdate() updates the transformation matrices saved in the snapshots for the subassemblies and their components with respect to the top-level assembly snapshot.
    Snapshots in Drawing Views
    Functions Introduced:
  • ProSnapshotAllowedInDrawingSet()
    		•
  • ProSnapshotAllowedInDrawingGet()
    		•
    The function ProSnapshotAllowedInDrawingSet() assigns the active snapshot of the top-level assembly to be available or unavailable in drawings. Set the argument allow to PRO_B_TRUE to make the snapshot available in drawings.
    The function ProSnapshotAllowedInDrawingGet() determines if the active snapshot is allowed in drawings. The argument p_is_allowed is PRO_B_TRUE if the snapshot is allowed in drawings.