External Objects
This section describes the Creo Object TOOLKIT C++ methods that enable you to create and manipulate external objects.
Summary of External Objects
External objects are objects created by an application that is external to Creo Parametric. Although these objects can be displayed and selected within a Creo Parametric session, they cannot be independently created by Creo Parametric. Using Creo Object TOOLKIT C++ methods, you can define and manipulate external objects, which are then stored in a model database.
Note
External objects are limited to text and wireframe entities. In addition, external objects can be created for parts and assemblies only. That is, external objects can be stored in a part or assembly database only.
In Creo Object TOOLKIT C++ application, an external object is defined by a wfcExternalObject object. This DHandle identifies an external object in the Creo Parametric database, which contains the following information for the object:
•  Object class—A class of external objects is a group that contains objects with similar characteristics. All external objects must belong to a class. Object class is contained in the wfcExternalObjectClass object.
•  Object data—The object data contains information about the display and selection of an external object. Object data is contained in the wfcExternalObjectData object.
•  Object parameters—External objects can own parameters. You can use the wfcWParameter API to get, set, and modify external object parameters.
•  Object references—External objects can reference any Creo object. This functionality is useful when changes to Creo objects need to instigate changes in the external objects. The changes are communicated back to your Creo Object TOOLKIT C++ application via the callback methods.
•  Callback methods—Creo Object TOOLKIT C++ enables you to specify callback methods for a class of external objects. These methods are called whenever the external object owner or reference is deleted, suppressed, or modified. In this manner, the appearance and behavior of your external objects can depend on the object owner or reference.
External Objects and Object Classes
This section describes the Creo Object TOOLKIT C++ methods that relate to the creation and manipulation of external objects and object classes.
Note
This description does not address the display or selection of the external object. For more information see External Object Data.
Creating External Objects
Methods introduced:
  • wfcExternalObjectClass::CreateObject
    		•
  • wfcExternalObjectClass::GetName
    		•
  • wfcExternalObjectClass::GetType
    		•
    After the object class is registered, you can create the external object by calling the method wfcExternalObjectClass::CreateObject. The input arguments to this method is owner. (Currently, the owner of the external object can be a part or an assembly only.) To get the information of the newly created object, pass the data handle wfcExternalObject to the method wfcExternalObjectClass::CreateObject.
    When the external object is created, it is assigned an integer identifier that is persistent from session to session. The external object is saved as part of the model database and will be available when the model is retrieved next.
    Use the method wfcExternalObjectClass::GetName to retrieve the name of the external object class.
    Use the method wfcExternalObjectClass::GetType to retrieve the type of the external object class.
    External Object Owners
    Methods introduced:
  • wfcExternalObject::GetOwner
    		•
    The owner of an external object is set during the call to wfcExternalObjectClass::CreateObject. For example, the “owner” would be the part or assembly where the external object resides.
    The method wfcExternalObject::GetOwner retrieves the owner of an existing external object. To get the owner to an external object, pass the data handle pfcModelItem to the method wfcExternalObject::GetOwner.
    External Object Data
    Simply creating an external object does not allow the object to be displayed or selected in Creo Parametric. For this, you must supply external object data that is used, stored, and retrieved by Creo Parametric. The data is removed from the model database when the external object is deleted.
    External object data is described by the opaque workspace handle wfcExternalObjectData. The methods required to initialize and modify this object are specific to the type of data being created. That is, creating display data requires one set of methods, whereas creating selection data requires another.
    Once you have created a wfcExternalObjectData object, the manipulation of the external object data is independent of its contents: the methods required to add or remove data are the same for both display and selection data.
    Display Data for External Objects
    Display data gives information to Creo Parametric about how the external object appears in the model window. This data must include the color, scale, line type, and transformation of the external object. In addition, display data can include settings that override the user’s ability to zoom and spin the external object.
    Note
    Setting the display data does not result in the external object being displayed. To see the object, you must repaint the model window using the method pfcWindow::Repaint.
    Methods introduced:
  • wfcExternalObjectDisplayData::Create
    		•
    Use the method wfcExternalObjectDisplayData::Create to create a display data information for an external object. The input arguments are as follows:
    •  Ents—Specify the entities in the pfcCurveDescriptors object in the specified display data.
    •  EntityColors—Specify the entities in the pfcStdColors object in the specified display data.
    The method wfcExternalObjectDisplayData::Create returns the display properties of the external object in the wfcExternalObjectDisplayData object.
    Creating the External Object Entity
    Methods introduced:
  • wfcExternalObjectDisplayData::GetEntities
    		•
  • wfcExternalObjectDisplayData::SetEntities
    		•
  • wfcExternalObjectDisplayData::GetEntityColors
    		•
  • wfcExternalObjectDisplayData::GetEntityColors
    		•
    External objects are currently limited to text and wireframe entities. You can specify the entities to be displayed by creating an array of pfcCurveDescriptors objects that contain that necessary information. pfcCurveDescriptors is a union of specific entity structures, such as line, arrow, arc, circle, spline, and text. Note that when you specify the entities in the pfcCurveDescriptors array, the coordinate system used is the default model coordinate system.
    Use the method wfcExternalObjectDisplayData::GetEntities to retrieve the entities that make up an external object in a specified display data.
    After you have created the array of pfcCurveDescriptors objects, you can add entities to the display data by calling the method wfcExternalObjectDisplayData::SetEntities. The input argument to the method wfcExternalObjectDisplayData::SetEntities are the entities in the pfcCurveDescriptors object.
    Note
    The method wfcExternalObjectDisplayData::SetEntities supports only wfcENTITY_LINE and wfcENTITY_ARC entities. However, you can draw polygons as multiple lines, and circles as arcs of extent 2 pi.
    The methods wfcExternalObjectDisplayData::GetEntityColors and wfcExternalObjectDisplayData::SetEntityColors retrieve and set the display data for a list of entities and the color for each entity. The input argument to the method wfcExternalObjectDisplayData::SetEntityColors are the list of entities in the pfcStdColors object.
    External Object Display Properties
    Methods introduced:
  • wfcExternalObjectData::GetType
    		•
  • wfcExternalObjectDisplayData::GetProperties
    		•
  • wfcExternalObjectDisplayData::SetProperties
    		•
    By default, when users spin or zoom in on a model, external objects are subjected to the same spin and zoom scale as the model. In addition, by default external objects are always displayed, even if the owner or reference objects are suppressed. Setting external object display properties within display data enables you to change these default behaviors.
    The method wfcExternalObjectData::GetType retrieves the type of property in specified external object data. To specify which type of property you want to retrieve, pass one of the values in the enumerated type wfcExternalObjectDataType to this method.
    The methods wfcExternalObjectDisplayData::GetProperties and wfcExternalObjectDisplayData::SetProperties retrieve and set the display properties in the specified display data. The input argument to the method wfcExternalObjectDisplayData::SetProperties are the display properties in the wfcExternalObjectDisplayDataProperties object.
    External Object Color
    Methods introduced:
  • wfcExternalObjectDisplayData::GetDisplayColor
    		•
  • wfcExternalObjectDisplayData::SetDisplayColor
    		•
    The enumerated type pfcStdColor specifies the colors available for external objects.
    The methods wfcExternalObjectDisplayData::GetDisplayColor and wfcExternalObjectDisplayData::SetDisplayColor retrieve and set the object color in the specified display data.
    Line Styles for External Objects
    Methods introduced:
  • wfcExternalObjectDisplayData::GetLineStyle
    		•
  • wfcExternalObjectDisplayData::SetLineStyle
    		•
    The enumerated type pfcStdLineStyle specifies the line styles available for specifies the line styles available for external objects.
    The methods wfcExternalObjectDisplayData::GetLineStyle and wfcExternalObjectDisplayData::SetLineStyle retrieve and set the object line style in the specified display data.
    External Object Scale
    Methods introduced:
  • wfcExternalObjectDisplayData::GetScale
    		•
  • wfcExternalObjectDisplayData::SetScale
    		•
    To vary the size of your external object without altering the entities themselves, you must specify an object scale factor as part of the display data.
    The methods wfcExternalObjectDisplayData::GetScale and wfcExternalObjectDisplayData::SetScale retrieve and set the scale factor in the specified display data.
    Transformation of the External Object
    Methods introduced:
  • wfcExternalObjectDisplayData::GetTransormationMatrix
    		•
  • wfcExternalObjectDisplayData::SetTransormationMatrix
    		•
    You can transform the local coordinates from model coordinates using the three-dimensional transformational matrix.
    The method wfcExternalObjectDisplayData::GetTransormationMatrix retrieve the transformation matrix contained in a particular set of display data.
    To a perform a coordinate transformation on an external object, use the method wfcExternalObjectDisplayData::SetTransormationMatrix to set the transformation matrix within the associated display data. The input argument to the method wfcExternalObjectDisplayData::SetTransormationMatrix is the transformation matrix in the pfcMatrix3D object.
    Selection Data for External Objects
    Methods introduced:
  • wfcExternalObjectSelectionBoxData::Create
    		•
  • wfcExternalObjectSelectionBoxData::SetBoxes
    		•
  • wfcExternalObjectSelectionBoxData::GetBoxes
    		•
    Use the method wfcExternalObjectSelectionBoxData::Create to create a selection data information for the specified external object. This method returns the selection data for the external object as a wfcExternalObjectSelectionBoxData object.
    Selection boxes are specified as part of the external object selection data. These selection boxes indicate locations in which mouse selections will cause the external object to be selected. For the selection to be possible, you must designate a set of “hot spots,” or selection boxes for the object.
    A selection box is defined by the pair of points contained in a wfcSelectionBoxes object. The coordinates of the points are specified in the external object's coordinate system (the default coordinates). The line between the points forms the diagonal of the selection box; the edges of the box lie parallel to the coordinate axes of the external object.
    Note
    PTC recommends that the size and arrangement of the selection boxes be dependent on the size and shape of the external object. If the external object is compact and uniformly distributed in all coordinate directions, one selection box will probably suffice.
    However, if the external object is distributed non-uniformly, or is interfering with other objects, you must designate more specific locations at which selection should occur.
    The method wfcExternalObjectSelectionBoxData::GetBoxes retrieves the list of selection boxes in a given selection data.
    To set the selection boxes within the selection data, call the method wfcExternalObjectSelectionBoxData::SetBoxes and pass as input a pointer to a list of wfcSelectionBoxes objects. This enables your external object to have more than one associated selection box.
    Manipulating External Object Data
    Methods introduced:
  • wfcExternalObject::AddData
    		•
  • wfcExternalObject::GetData
    		•
  • wfcExternalObject::ModifyData
    		•
  • wfcExternalObject::RemoveData
    		•
  • wfcExternalObject::GetClass
    		•
    The methods in this section enable you to manipulate how the external object data relates to the object itself.
    To add new data to an external object, pass the data handle wfcExternalObjectData to the method wfcExternalObject::AddData.
    The method wfcExternalObject::ModifyData sets the contents of existing object data.
    The method wfcExternalObject::GetData retrieves the handle for the display or selection data associated with an external object. To specify which type of data you want to retrieve, pass one of the values in the enumerated type wfcExternalObjectDataType to this method.
    Use the method wfcExternalObject::RemoveData to remove data from an external object.
    Use the method wfcExternalObject::GetClass to retrieve the class of an external object.
    External Object References
    You can use external object references to make external objects dependent on model geometry. For example, consider an external object that is modeled as the outward-pointing normal of a surface. Defining the surface as a reference enables the external object to behave appropriately when the surface is modified, deleted, or suppressed.
    In general, an external object can reference any of the geometry that belongs to its owner. In addition, if the owner belongs to an assembly, the external object can also reference the geometry of other assembly components, provided that you supply a valid component path.
    Note
    Setting up the references for an external object does not fully define the dependency between the object and the reference. You must also specify the callback method to be called when some action is taken on the reference.
    Creating External Object References
    Methods introduced:
  • wfcExternalReferenceInfo::Create
    		•
  • wfcExternalReferenceInfo::GetType
    		•
  • wfcExternalReferenceInfo::SetType
    		•
  • wfcExternalReferenceInfo::GetExtRefs
    		•
  • wfcExternalReferenceInfo::SetExtRefs
    		•
    Use the method wfcExternalReferenceInfo::Create to create an external reference information object. The input arguments are as follows:
    •  type—Specify the type of the external reference.
    •  extRefs—Specify the sequence of external feature references.
    You might need to use “reference types” to differentiate among the references of an external object.
    The method wfcExternalReferenceInfo::GetType retrieve the reference type of the specified reference in an external reference information object. To specify which type of external reference to want to retrieve, pass one of the values in the enumerated type wfcExternalReferenceType to this method.
    Use the method wfcExternalReferenceInfo::SetType to set a reference type.
    The method wfcExternalReferenceInfo::GetExtRefs retrieve the sequence of external feature references in an external reference information object.
    Use the method wfcExternalReferenceInfo::SetExtRefs to set the external feature reference. The input argument are the external feature references in the wfcWExternalFeatureReferences object.