Event-driven Programming: External Objects
This section describes the Creo TOOLKIT functions 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 can not be independently created by Creo Parametric. Using Creo TOOLKIT functions, 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 a Creo TOOLKIT application, an external object is defined by a ProExtobj 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 ProExtobjClass object.
•  Object data—The object data contains information about the display and selection of an external object. Object data is contained in the ProWExtobjdata object.
•  Object parameters—External objects can own parameters. You can use the ProParameter API to get, set, and modify external object parameters.
•  Object references—External objects can reference any Creo Parametric object. This functionality is useful when changes to Creo Parametric objects need to instigate changes in the external objects. The changes are communicated back to your Creo TOOLKIT application via the callback functions.
•  Callback functions—Creo TOOLKIT enables you to specify callback functions for a class of external objects. These functions 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 TOOLKIT functions that relate to the creation and manipulation of external objects and object classes. Note that this description does not address the display or selection of the external object. For more information on this topic, seeExternal Object Data .
Creating External Object Classes
Functions Introduced:
  • ProExtobjClassCreate()
    		•
  • ProExtobjClassDelete()
    		•
    Every external object must belong to a class. The concept of a “class” enables you to group together external objects that exhibit similar characteristics. In addition, classes permit multiple applications to create external objects without conflict.
    The ProExtobjClass object contains the name and type of an external object class. PTC recommends that you supply a class name unique to your application. The type of the class is an integer that should vary among the different classes.
    To register an external object class, pass a completed ProExtobjClass object to the function ProExtobjClassCreate(). To unregister a class, call the function ProExtobjClassDelete().
    Creating External Objects
    Functions Introduced:
  • ProExtobjCreate()
    		•
  • ProExtobjDelete()
    		•
  • ProExtobjClassGet()
    		•
    After the object class is registered, you can create the external object by calling the function ProExtobjCreate(). This function requires as input the object class and owner of the external object. (Currently, the owner of the external object can be a part or an assembly only.) As output, this function gives a pointer to the handle of the newly created external object.
    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.
    To delete an external object, call the function ProExtobjDelete(). This function requires as input both the object to be deleted and the class to which it belongs. To determine the class of an external object, call the function ProExtobjClassGet().
    External Object Owners
    Functions Introduced:
  • ProExtobjOwnerobjGet()
    		•
  • ProExtobjOwnerobjSet()
    		•
    The owner of an external object is set during the call to ProExtobjCreate(). For example, the “owner” would be the part or assembly where the external object resides.
    To determine the owner of an external object, call the function ProExtobjOwnerobjGet(). To change the owner, call the function ProExtobjOwnerobjSet().
    Recycling External Object Identifiers
    Functions Introduced:
  • ProExtobjReusableSet()
    		•
  • ProExtobjReusableGet()
    		•
  • ProExtobjReusableClear()
    		•
    By default, the identifier of an external object is not “recycled.” When you delete an external object, its identifier is not freed for reuse by external objects that are subsequently created.
    You can override this default behavior using the function ProExtobjReusableSet(). This function enables external object identifiers to be recycled. To determine whether external object identifiers are set to be recyclable, call the function ProExtobjReusableGet(). To reset to the default behavior (no recycling), call the function ProExtobjReusableClear().
    External Object Parameters
    As with features and models, external objects can also have user-defined parameters. Although you can specify parameters for an external object, there is no method to retrieve these parameters interactively in Creo Parametric. Therefore, external object parameters are a way to store information in the Creo Parametric model that is not accessible to end-users.
    You can convert a ProExtobj object to a ProModelitem object by casting. See the Core: Parameters section for more information.
    External Types and Identifiers for External Objects
    Functions Introduced:
  • ProExtobjExttypeSet()
    		•
  • ProExtobjExttypeGet()
    		•
  • ProExtobjExtidSet()
    		•
  • ProExtobjExtidGet()
    		•
    ProExtobj is a DHandle that contains the type, identifier, and owner of an external object. This information identifies the external object in the Creo Parametric database.
    Some applications might require additional type and identifier information to be assigned to external objects. That is, the type and identifier may need to be independent of those assigned within Creo Parametric.
    The function ProExtobjExttypeSet() sets an external type for an external object. The function ProExtobjExttypeGet() obtains the external type for the specified external object.
    The function ProExtobjExtidSet() sets an external integer identifier for the specified external object. To get the external identifier for a given external object, call the function ProExtobjExtidGet().
    Visiting External Objects
    Function Introduced:
  • ProExtobjVisit()
    • Using the traversal functions for external objects, you can visit each external object in turn, and perform some action or filtration on it. The function ProExtobjVisit() specifies action and filter functions of type ProExtobjVisitAction() and ProExtobjFilterAction(), respectively.
    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 ProWExtobjdata. The functions 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 functions, whereas creating selection data requires another.
    Once you have created a ProWExtobjdata object, the manipulation of the external object data is independent of its contents: the functions required to add or remove data are the same for both display and selection data.
    The following sections describe the Creo TOOLKIT functions that relate to external object data. The sections are as follows:
    •  Display Data for External Objects
    •  Selection Data for External Objects
    •  Manipulating External Object Data
    Display Data for External Objects
    Display data gives information to Creo Parametric about how the external object is to appear 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 that setting display data does not result in the external object being displayed. To see the object, you must repaint the model window using the function ProWindowRepaint().
    Allocating Display Data
    Function Introduced:
  • ProDispdatAlloc()
    		•
    For display data, the workspace handle ProWExtobjdata is allocated using the function ProDispdatAlloc(). Because the other Creo TOOLKIT display data functions require ProWExtobjdata as input, you must call ProDispdatAlloc() before calling the other functions in this section.
    The input for ProDispdatAlloc() is the address of a ProWExtobjdata object that you declare in your application. You must set this ProWExtobjdata object to NULL before passing its address to ProDispdatAlloc().
    Creating the External Object Entity
    Functions Introduced:
  • ProDispdatEntsSet()
    		•
  • ProDispdatEntsGet()
    		•
  • ProDispdatEntsWithColorSet()
    		•
    External objects are currently limited to text and wireframe entities. You can specify the entities to be displayed by creating an array of ProCurvedata objects that contain that necessary information. ProCurvedata 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 ProCurvedata array, the coordinate system used is the default model coordinate system.
    After you have created the array of ProCurvedata objects, you can add entities to the display data by calling the function ProDispdatEntsSet(). Note that ProDispdatEntsSet() supports only PRO_ENT_LINE and PRO_ENT_ARC entities. However, you can draw polygons as multiple lines, and circles as arcs of extent 2 pi.
    To obtain the entities that make up an external object, call the function ProDispdatEntsGet().
    The function ProDispdatEntsWithColorSet() sets the display data for a list of entities and the color for each entity. The entities that are supported are:
    •  PRO_ENT_LINE
    •  PRO_ENT_ARC
    The entities are specified in the local coordinates of the external object. Use the function ProDispdatTrfSet() to transform the local coordinates to model coordinates.
    Example 1: Creating an External Object shows how to specify an external object that is composed of line segments.
    Transformation of the External Object
    Functions Introduced:
  • ProDispdatTrfSet()
    		•
  • ProDispdatTrfGet()
    		•
  • ProExtobjScreentrfGet()
    		•
    To a perform a coordinate transformation on an external object, you must set the transformation matrix within the associated display data. To do this, call the function ProDispdatTrfSet() and pass the transformation matrix as an input argument. To obtain the transformation matrix contained in a particular set of display data, call the function ProDispdatTrfGet().
    Example 1: Creating an External Object implements a transformation from default coordinates to a coordinate system that is dependent on the orientation of a selected surface.
    Note
    Even if you do not want to transform your external object from the default coordinate system, you must specify a transformation matrix. In this case, pass the identity matrix to ProDispdatTrfSet(). If you omit this step, your external object will not be displayed.
    To obtain the complete transformation of an object from external object coordinates (default coordinates) to screen coordinates, call the function ProExtobjScreentrfGet().
    Note
    In the assembly mode, ProExtobjScreentrfGet() is applicable for external objects owned only by the top assembly model. Use the function ProDispdatTrfGet() to retrieve the transformation of external objects in sub-models in the assembly mode. In the part mode, ProExtobjScreentrfGet() is applicable for all objects.
    External Object Display Properties
    Functions Introduced:
  • ProDispdatPropsSet()
    		•
  • ProDispdatPropsGet()
    		•
    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 ProExtobjDispprops object is an enumerated type that contains the possible settings for display properties. To set any of these properties within display data, create a ProExtobjDispprops array that contains your settings and pass this array to the function ProDispdatPropsSet(). To determine the display settings for specified display data, call the function ProDispdatPropsGet().
    The settings contained in ProExtobjDispprops are as follows:
    •  PRO_EXTOBJ_ZOOM_INVARIANT—Sets the external object to be invariant with the zoom scale or magnification of the model. The object appears the same size at all times.
    •  PRO_EXTOBJ_SPIN_INVARIANT—Set the external object to be invariant with the spin or orientation of the model. The object has the same orientation at all times.
    •  PRO_EXTOBJ_BLANKED—Blank the display of the external object. This setting is useful if you want the suppress the external object when the reference or owner objects are suppressed.
    External Object Color
    Functions Introduced:
  • ProDispdatColorGet()
    		•
  • ProDispdatColorSet()
    		•
    The enumerated type ProColortype specifies the colors available for external objects. To set the object color within display data, call the function ProDispdatColorSet(). To determine the color in the specified display data, use ProDispdatColorGet().
    Line Styles for External Objects
    Functions Introduced:
  • ProDispdatLinestyleSet()
    		•
  • ProDispdatLinestyleGet()
    		•
    The enumerated type ProLinestyle specifies the line styles available for external objects. To set the object line style within the display data, call the function ProDispdatLinestyleSet(). To determine the line style in the specified display data, use ProDispdatLinestyleGet().
    External Object Scale
    Functions Introduced:
  • ProDispdatScaleSet()
    		•
  • ProDispdatScaleGet()
    		•
    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. To set the scale factor, call the function ProDispdatScaleSet(). To determine the scale factor in the specified display data, use ProDispdatScaleGet().
    Example 1: Creating an External Object shows how to set the scale of an object to be dependent on the size of the owner object.
    Selection Data for External Objects
    Functions Introduced:
  • ProSeldatAlloc()
    		•
  • ProSeldatSelboxesSet()
    		•
  • ProSeldatSelboxesGet()
    		•
    You can select external objects using the Creo TOOLKIT selection function ProSelect(), with the selection option ext_obj. For this selection to be possible, however, you must designate a set of “hot spots,” or selection boxes for the object. These selection boxes indicate locations in which mouse selections will cause the external object to be selected. Selection boxes are specified as part of the external object selection data.
    The function ProSeldatAlloc() allocates selection data in preparation for the specification of the selection boxes.
    A selection box is defined by the pair of points contained in a ProSelbox 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. To set the selection boxes within the selection data, call the function ProSeldatSelboxesSet() and pass as input a pointer to a list of ProSelbox objects. This enables your external object to have more than one associated selection box.
    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 nonuniformly, or is interfering with other objects, you must designate more specific locations at which selection should occur.
    To obtain the list of selection boxes in a given selection data, call the function ProSeldatSelboxesGet().
    The ProSelect() function returns an array of ProSelection objects. To obtain a ProExtobj object from a ProSelection object, call the function ProSelectionModelitemGet() and cast the output ProModelitem directly into ProExtobj. (ProExtobj and ProModelitem are DHandles with identical declarations.)
    Selecting the Node from the External Application Tree
    The tree created by an external application (SPEOS tree) is similar to the Creo Parametric model tree. Each node of this tree represents an external object that has been created by the application. The external objects could be different types of entities, such as, light sources, light sensors, and so on.
    Functions Introduced:
  • ProSelectExternalhighlightRegister()
    		•
  • ProSelectExternalselectionRecord()
    		•
    The function ProSelectExternalhighlightRegister() registers the call back functions when you select or deselect a node in the user tree or an object in the graphics window. The notification function ProSelectionStartNotify() is called when the function ProSelect() is activated. It notifies the application about entering ProSelect(). The call back function ProSelectionExtHighlightAct() is called when you select or deselect an external object. The TOOLKIT application will highlight the external object or remove the highlight according to the selection. On clicking a tree node, the application creates a ProSelection object and uses the function ProSelectExternalselectionRecord() to pass it to ProSelect(). The input arguments of this function are:
    •  selection—Specifies the selection object created by an external application.
    •  action—Specifes the type of selection. The valid values are:
    ○  PRO_SELECT_OVERRIDE—For unmodified selection
    ○  PRO_SELECT_TOGGLE—For CTRL modified selection.
    The function ProSelectionEndNotify() notifies the application on exiting the function ProSelect().
    Manipulating External Object Data
    Functions Introduced:
  • ProExtobjdataAdd()
    		•
  • ProExtobjdataSet()
    		•
  • ProExtobjdataGet()
    		•
  • ProExtobjdataRemove()
    		•
  • ProExtobjdataFree()
    		•
    The previous two sections describe how to create and modify external object data. In the case of both display and selection data, the data creation process results in the opaque workspace handle ProWExtobjdata. The functions 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 ProWExtobjdata to the function ProExtobjdataAdd(). To set the contents of existing object data, call the function ProExtobjdataSet().
    The function ProExtobjdataGet() obtains the handle for the display or selection data associated with an external object. To specify which type of data you want to retrieve, pass to this function one of the values in the enumerated type ProExtobjdataType. The declaration is as follows: 
        typedef enum
    {
      PRO_EXTOBJDAT_DISPLAY,
      PRO_EXTOBJDAT_SELBOX
    } ProExtobjdataType;
    To remove data from an external object, use the function ProExtobjdataRemove(). To free the memory occupied by external object data, call the function ProExtobjdataFree().
    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 function to be called when some action is taken on the reference.
    Creating External Object References
    Functions Introduced:
  • ProExtobjRefAlloc()
    		•
  • ProExtobjRefFree()
    		•
  • ProExtobjRefselectionSet()
    		•
  • ProExtobjRefselectionGet()
    		•
  • ProExtobjReftypeSet()
    		•
  • ProExtobjReftypeGet()
    		•
  • ProExtobjRefAdd()
    		•
  • ProExtobjRefRemove()
    		•
    The ProWExtobjRef object is an opaque workspace handle that defines an external object reference. To allocate the memory for a new external object reference, call the function ProExtobjRefAlloc(). To free the memory occupied by an object reference, call the function ProExtobjRefFree().
    If you have the ProSelection object that corresponds to your intended reference geometry, you can set this ProSelection to be the reference by calling the function ProExtobjRefselectionSet(). To obtain the ProSelection object for a specified reference, use ProExtobjRefselectionGet().
    You might need to use “reference types” to differentiate among the references of an external object. To set a reference type, call the function ProExtobjReftypeSet(). To obtain the reference type of the specified reference, call the function ProExtobjReftypeGet().
    Once you have set the ProSelection and the reference type for an external object reference, you must add the reference to the external object using the function ProExtobjRefAdd(). To remove a reference from an external object, use ProExtobjRefRemove().
    Visiting External Object References
    Function Introduced:
  • ProExtobjRefVisit()
    		•
    Using the traversal functions for external object references, you can visit each external object reference in turn, and perform some action or filtration on it. The function ProExtobjRefVisit() specifies action and filter functions of type ProExtobjRefVisitAction() and ProExtobjRefFilterAction(), respectively.
    Callbacks for External Objects
    Functions Introduced:
  • ProExtobjCBAct()
    		•
  • ProExtobjCBEnable()
    		•
  • ProExtobjCallbacksSet()
    		•
    External objects are associated with their owners and the references that you specify. Currently, the callbacks mechanism for external objects enables you to receive notification when the reference is deleted, modified, or suppressed. Your callback function can respond in a manner appropriate for the action taken on the reference.
    The ProExtobjCallbacks object is a structure that specifies the callback functions for each action on the external object's owner or reference. Each callback function is specified by a function pointer of type ProExtobjCBAct. When you create an external object class, you should also fill in a ProExtobjCallbacks object for that class. To set the callbacks for the class, call the ProExtobjCallbacksSet() function.
    •  Currently, the only supported callbacks for external objects are for deletion, modification, and suppression.
    •  You cannot use a callback for an external object that references a Creo Parametric feature (and not some geometry of it).
    The ProExtobjCallbacks data structure is defined as follows: 
         typedef struct
     {
       int              enabled_cbs;
       ProExtobjCBAct   display_CB;          /* not yet implemented */
       ProExtobjCBAct   select_CB;           /* not yet implemented */
       ProExtobjCBAct   owner_modify_CB;     /* not yet implemented */
       ProExtobjCBAct   owner_suppress_CB;   /* not yet implemented */
       ProExtobjCBAct   owner_delete_CB;     /* not yet implemented */
       ProExtobjCBAct   ref_modify_CB;
       ProExtobjCBAct   ref_suppress_CB;
       ProExtobjCBAct   ref_delete_CB;
     } ProExtobjCallbacks;
    The first field, enabled_cbs, is a flag that enables and disables the callback functions. Set each of the other fields in the structure to the name of the callback function appropriate for each action. To enable or disable the callback functions for a particular action and object class, call the function ProExtobjCBEnable().
    As shown in the previous structure, the external objects callbacks are implemented only for cases where the reference is modified, suppressed, or deleted. For this reason, you must exercise caution when enabling callbacks using ProExtobjCBEnable(). One of the inputs of the function is an action bitmask that specifies which callback actions are to be enabled. The action bitmask is composed of members of the enumerated type ProExtobjAction. The values of the enumerated type are as follows: 
    typedef enum
{
   PRO_EO_ALT_DISPLAY    = (1 << 6), 
                           /* alternate display --  
                              not implemented */
   PRO_EO_ALT_SELECT     = (1 << 7), 
                           /* alternate selection --
                              not implemented */
   PRO_EO_ACT_OWN_MODIF  = (1 << 9),
                           /* not implemented */
   PRO_EO_ACT_OWN_SUPPR  = (1 << 10),
                           /* not implemented */
   PRO_EO_ACT_OWN_DELETE = (1 << 11),
                           /* not implemented */
   PRO_EO_ACT_REF_MODIF  = (1 << 13),
   PRO_EO_ACT_REF_SUPPR  = (1 << 14),
   PRO_EO_ACT_REF_DELETE = (1 << 15)
} ProExtobjAction;
    The action bitmask must not contain any callback actions that are not supported. Given the comments in the ProExtobjCallbacks structure, the only allowed callback actions are PRO_EO_ACT_REF_MODIF, PRO_EO_ACT_REF_SUPPR, and PRO_EO_ACT_REF_DELETE.
    The following table describes the actions given in the ProExtobjCallbacks data structure.
    Callback Type
    When it is Triggered
    display_CB
    The external object is displayed. Currently, this is not implemented.
    select_CB
    The external object is selected. Currently, this is not implemented.
    owner_modify_CB
    The owner of the external object is modified. Currently, this is not implemented.
    owner_suppress_CB
    The owner of the external object is suppressed. Currently, this is not implemented.
    owner_delete_CB
    The owner of the external object is deleted. Currently, this is not implemented.
    ref_modify_CB
    The reference of the external object is modified.
    ref_suppress_CB
    The reference of the external object is suppressed.
    ref_delete_CB
    The reference of the external object is deleted.
    Warning Mechanism for External Objects
    Functions Introduced:
  • ProExtobjClassWarningEnable()
    		•
  • ProExtobjClassWarningDisable()
    		•
  • ProExtobjWarningEnable()
    		•
  • ProExtobjWarningDisable()
    		•
    When users perform some action on the references of an external object, you might want to display a warning message to ask users to confirm the action. Creo TOOLKIT includes functions that implement such warnings, either for all external objects in a class or for individual external objects. For example, if a user attempts to delete a feature whose geometry is referenced by a class of external objects, the Creo TOOLKIT warning mechanism, if enabled, would open a warning window that states the potential problem. The users would pick Yes to continue with the deletion, or No to abort the deletion.
    To enable the warnings for a class of external objects, call the function ProExtobjClassWarningEnable(). Note that all external objects that belong to the class will inherit the enabled warning if they are created subsequent to the call to ProExtobjClassWarningEnable().
    The input arguments to ProExtobjClassWarningEnable() are the class object ProExtobjClass and an action bitmask composed of members of the enumerated type ProExtobjAction (described in the section Callbacks for External Objects). The action bitmask specifies for which actions the warning is to be displayed. Currently, the only supported actions are PRO_EO_ACT_REF_SUPPR (suppression of the reference) and PRO_EO_ACT_REF_DELETE (deletion of the reference).
    To have the warnings displayed for both reference suppression and deletion, the call to ProExtobjClassWarningEnable() would appear as follows: 
        ProExtobjClassWarningEnable (&User_arrow_class,
    PRO_EO_ACT_REF_SUPPR|PRO_EO_ACT_REF_DELETE);
    In this call, User_arrow_class is declared as a ProExtobjClass (an external object class).
    To disable the warnings for a class of external objects, call ProExtobjClassWarningDisable(). Note that all external objects that belong to the class will inherit the disabled warning if they are created subsequent to the call to the function ProExtobjClassWarningDisable().
    To enable warnings for a single external object (not the entire class), call the function ProExtobjWarningEnable(). This function is similar to ProExtobjClassWarningEnable() except the first argument for ProExtobjWarningEnable() is a pointer to a ProExtobj object. To disable the warnings for a single external object, call the function ProExtobjWarningDisable().
    Example 1: Creating an External Object
    The sample code in the file UgExtobjCreate.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_extobj shows how to create an external object at a location specified by the user. The external object is a green arrow that is aligned with the normal to a selected surface.
    Note
    For the sake of simplicity, the example does not implement selection data.