Element Trees: References
This section describes functions that provide access to reference objects as an alternative for accessing the information as selections.
Overview of Reference Objects
Reference objects are an alternative method for representing a geometric reference in Creo Parametric. Geometric references are usually represented using the ProSelection structure. Since ProSelection is designed as the result of an interactively selected item, it lacks some capabilities to provide complete meaning as a geometric reference.
The opaque handle ProReference provides complete functionality for geometric referencing including functions to access multiple or missing references.
Reading References
Functions Introduced:
  • ProReferenceStatusGet()
    		•
  • ProReferenceIsLocalcopy()
    		•
  • ProReferenceTypeGet()
    		•
  • ProReferenceIdGet()
    		•
  • ProReferenceOwnerGet()
    		•
  • ProReferenceOwnerMdlnameGet()
    		•
  • ProReferenceOriginaltypeGet()
    		•
  • ProReferenceOriginalidGet()
    		•
  • ProReferenceOriginalownerGet()
    		•
  • ProReferenceOriginalownerMdlnameGet()
    		•
  • ProReferenceAsmcomppathGet()
    		•
  • ProReferenceParamsGet()
    		•
  • ProReferencePointGet()
    		•
  • ProReferenceToSelection()
    		•
  • ProSelectionToReference()
    		•
  • ProReferencearrayToSelections()
    		•
  • ProSelectionarrayFree()
    		•
  • ProSelectionarrayToReferences()
    		•
  • ProReferenceFree()
    		•
  • ProReferencearrayFree()
    		•
    The function ProReferenceStatusGet() identifies the status of the reference. Typically references are of status PRO_REF_ACTIVE, indicating that the reference is available and its geometry is usable for construction of features. Other reference statuses include:
    •  PRO_REF_MISSING – The reference is to geometry that is inactive in the model. When reading the element tree of a feature that modifies the geometry it references (for example, a round of edge removes the edge) the references will have this status.
    •  PRO_REF_NOT_FOUND – Similar to PRO_REF_MISSING. The function indicates a reference that is critical to the feature that uses the function.
    •  PRO_REF_FROZEN – The reference is to geometry in a component frozen due to other missing references.
    •  PRO_REF_FROZEN_PLACE, PRO_REF_SUPPRESSED,PRO_REF_EXCLUDED – Not returned by ProReferenceStatusGet().
    •  PRO_REF_INVALID – The reference is invalid in the context of the feature and the element in which it is used (for example, a non-linear edge used as direction reference for drafts or translations.)
    •  PRO_REF_ALTERNATE – The reference is using an alternate reference. The original reference information is available.
    Note
    Reference status is highly dependent on the model state at the time the reference was obtained. References obtained from a feature via ProFeatureElemtreeExtract() may become “Missing” or “Not found” due to changes in the geometry applied later in the feature list. To obtain the reference status for a given reference as it is seen by a feature, use ProInsertModeActivate() to revert the model to the state just after that feature is created.
    •  PRO_REF_WARNING—The referenced entity has a warning.
    Note
    References obtained from a feature that removes a geometric empty body can have a “Warning” or “Invalid” state. The statuses of the references are not stored in the models and are thrown at run time during feature creation, redefinition, or regeneration.
    The function ProReferenceIsLocalcopy() identifies if the reference is a local copy of the external reference. If the reference is a local copy, the original reference information is available as well.
    The function ProReferenceTypeGet() gets the type of handle that is referenced.
    The function ProReferenceIdGet() gets the item identity of the reference handle.
    The function ProReferenceOwnerGet() gets the ProMdl handle of the owner model for the reference. The output of these three functions provides access to the basic ProModelitem referenced by the ProReference handle. If the reference status is not PRO_REF_ACTIVE, some or all of this information may not be accessible (for example, the reference owner model is not accessible if the reference is to a geometry item in an unretrieved component). The function ProReferenceOwnerMdlnameGet() gets the reference owner name of the referenced geometry item, which may be available even if the model itself has not been retrieved.
    The functions ProReferenceOriginaltypeGet(), ProReferenceOriginalidGet(), ProReferenceOriginalownerGet(), ProReferenceOriginalownerMdlnameGet() get the original properties of a geometric reference handle. These could be different from the actively used type if the reference has been backed up, copied locally, or replaced with an alternate.
    The function ProReferenceAsmcomppathGet() gets the component path of a reference handle.
    The function ProReferenceParamsGet() gets the u-v parameters of a reference handle.
    The function ProReferencePointGet() gets the selected point of a reference handle.
    The function ProReferenceToSelection() gets and allocates a ProSelection containing a representation for this reference. The output of this function is the resulting ProSelection handle. This selection is independently allocated and should be freed using ProSelectionFree().
    The function ProSelectionToReference() gets and allocates a ProReference containing a representation for this selection. The output of this function is the resulting ProReference handle. This reference is independently allocated and should be freed using ProReferenceFree().
    The function ProReferencearrayToSelections() converts a reference ProArray to a selection ProArray. The input arguments for this function are
    •  references – The ProArray of reference handles.
    •  skip_unusable – PRO_B_TRUE to skip the processing of missing references that cannot be valid selections. PRO_B_FALSE to process all references.
    The output for this function is a selection that is a ProArray of selection handles. You can free this array using the function ProSelectionarrayFree().
    The function ProSelectionarrayToReferences() converts a selection ProArray to a reference ProArray. ProArray of selection handles is given as the input and the ProArray of reference handles is the output. Free this array using ProReferencearrayFree().
    The function ProReferenceFree() frees a reference handle.
    The function ProReferencearrayFree() frees a reference ProArray. This function also free each ProReference handle using ProReferenceFree().
    Modifying References
    Functions Introduced:
  • ProReferenceAlloc()
    		•
  • ProReferenceSet()
    		•
  • ProReferenceParamsSet()
    		•
  • ProReferencePointSet()
    		•
    The function ProReferenceAlloc() allocates a reference handle.
    The function ProReferenceSet() sets the referenced model item and optionally component path for the reference handle.
    The function ProReferenceParamsSet() sets the u-v parameters of a reference handle.
    The function ProReferencePointSet() sets the selected point of a reference handle.