Core: Models and Model Items
This section describes Creo TOOLKIT modes, models, and model items.
Modes
Functions Introduced:
  • ProModeCurrentGet()
    		•
  • ProSectionIsActive()
    		•
    The term “mode” in Creo Parametric refers to the type of model currently being edited by the user. The possible modes are given by the options listed under the command File ▶ New.
    The ProMode object in Creo TOOLKIT is an enumerated type, declared in the file ProMode.h, as are the prototypes for the mode functions.
    Find the name of the mode using the function ProModeCurrentGet(). The function ProModeCurrentGet() outputs the mode in which Creo Parametric is being used, in the form of the ProMode enumerated type. If there is no current model—for example, because no model has been retrieved, or because the user has selected File ▶ Close—the function returns an error status (PRO_TK_BAD_CONTEXT).
    The function ProSectionIsActive() checks if the sketcher is currently active even if the current mode is part or assembly.
    Models
    This section describes Creo TOOLKIT models. The topics are as follows:
    •  The ProMdl Object
    •  Creating Models
    •  Identifying Models
    •  Models in Session
    •  File Management Operations
    The ProMdl Object
    A model is a top-level object in a Creo Parametric mode. For example, in Part mode, the model is a part; in Assembly mode, the model is an assembly.
    The object ProMdl is therefore used for all those functions whose action applies to models of any type, such as file management operations and version stamps.
    The declaration of ProMdl is as follows: 
         typedef void* ProMdl;
    Instances of the ProMdl object are objects for the more specific Creo Parametric modes. For example, ProSolid is an instance of ProMdl, and ProAssembly and ProPart are instances of ProSolid. All these object types are represented in Creo TOOLKIT by opaque handles, and you can make conversions between the types by casting.
    Creating Models
    Functions Introduced
  • ProSolidMdlnameCreate()
    		•
  • ProMfgMdlCreate()
    		•
  • ProSection2DAlloc()
    		•
  • ProDrawingFromTmpltCreate()
    		•
  • ProDrawingFromTemplateCreate()
    		•
  • ProMdlStartAction()
    		•
    Creo TOOLKIT supports creation of models for Solids, Manufacturing, Section (two-dimensional only), and Drawing.
    See Creating a Solid for a complete description of ProSolidMdlnameCreate().
    For more information on ProMfgMdlCreate() see Creating a Manufacturing Model.
    Allocating a Two-Dimensional Section gives more details on ProSection2DAlloc().
    Creating Drawings from Templates has more information on the function ProDrawingFromTemplateCreate().
    Note
    The function ProDrawingFromTmpltCreate() will be deprecated in a future release. Use the function ProDrawingFromTemplateCreate() instead.
    The notification function ProMdlStartAction() is a type for a callback function for PRO_MDL_START. This function changes the way users can create models by replacing the Creo Parametric model template dialog box with a user-specified action.
    The user-specified action contains user-programmed activities that allow customization of new models by applying templates with more inputs than model creation “on-the-fly” or the standard Creo Parametric template.
    The callback function is activated after the user selects OK from the File ▶ New dialog box, but only if the Use Default Template checkbox is not selected. The user’s application must create a new model of the same type and subtype specified by the callback function.
    Setting the configuration option force_new_file_options_dialog to yes forces the Use Default Template button to be hidden, and calls the callback for all models created through the File ▶ New dialog.
    This function supports all model types.
    See Event-driven Programming: Notifications for more data on using callback functions.
    Identifying Models
    Functions Introduced:
  • ProMdlMdlnameGet()
    		•
  • ProMdlOriginGet()
    		•
  • ProMdlExtensionGet()
    		•
  • ProMdlDirectoryPathGet()
    		•
  • ProMdlTypeGet()
    		•
  • ProMdlDisplaynameGet()
    		•
  • ProMdlCommonnameGet()
    		•
  • ProMdlCommonnameSet()
    		•
  • ProMdlObjectdefaultnameGet()
    		•
  • ProMdlnameInit()
    		•
  • ProMdlIdGet()
    		•
  • ProMdlActiveGet()
    		•
  • ProMdlSubtypeGet()
    		•
  • ProMdlFiletypeGet()
    		•
  • ProFileSubtypeGet()
    		•
  • ProMdlToModelitem()
    		•
    The object ProMdl is an opaque handle, and is therefore volatile. It cannot be used to refer to models that are not in memory in Creo Parametric, for example. To reference a model in a way that is valid for models not in memory, and also persistent across sessions of Creo Parametric, use the model name and type.
    The functions ProMdlMdlnameGet() and ProMdlTypeGet() provide the name and type of a model, given its ProMdl handle. The type of a model is expressed in terms of the enumerated type ProMdlType. From Creo Parametric 3.0 onward, this enumerated data type contains an additional value PRO_MDL_CE_SOLID that represents a Layout model. Creo TOOLKIT functions will only be able to read models of type Layout, but will not be able to pass Layout models as input to other functions. PTC recommends that you review all Creo TOOLKIT applications that use the enumerated type ProMdlType and modify the code as appropriate to ensure that the applications work correctly.
    The function ProMdlOriginGet() retrieves the full source path of the model, that is, the path from where the specified model has been opened. It returns NULL if the specified model is new in the session, and has not been saved. For instances, it returns the full path of the file that created the instance. For example, the accelerator file if applicable or otherwise the generic.
    The function ProMdlExtensionGet() retrieves the file extension for the specified model.
    The function ProMdlDirectoryPathGet() returns the file path where the specified model would be saved. It specifies the target home directory for the model.
    The function ProMdlDisplaynameGet() returns the name of the model, which is displayed in the Creo Parametric user interface. The name is displayed in the graphics area, such as, the model tree, window title, and so on. If the model is an instance of native Creo model, the display name is the instance name. For configurations or instances of non-native models, the display name consists of the model name along with the configuration name or instance name. If you specify the input argument include_ext as PRO_B_TRUE, then the display name returned by the function also includes the file extension of the model.
    The functions ProMdlCommonnameGet() and ProMdlCommonnameSet() obtain and assign the common name of a model, respectively. This name is used to identify the model in a Product Database Management system such as Windchill PDMLink.
    Note
    ProMdlCommonnameSet() can modify the name only for models that are not yet owned by Windchill PDMLink, or in certain situations if the configuration option let_proe_rename_pdm_objects is set to yes.
    The function ProMdlObjectdefaultnameGet() returns the next available default name for a given model type. The type of the model is specified by the enumerated type ProType and has one of the following values:
    •  PRO_PART
    •  PRO_ASSEMBLY
    •  PRO_CABLE
    •  PRO_DRAWING
    •  PRO_REPORT
    •  PRO_2DSECTION
    •  PRO_3DSECTION
    •  PRO_LAYOUT
    •  PRO_DWGFORM
    •  PRO_MARKUP
    Note
    For each of the above types, ProMdlObjectdefaultnameGet() returns the next available default name, for example PRT00# for PRO_PART or DRW00# for PRO_DRAWING, where # specifies the part or drawing number. This number depends on the following factors:
    •  Models present in the active Creo Parametric session
    •  Files in the current working directory
    •  Connection to an active server with the autonumber option enabled
    Thus, if no object with the specified name is actually created, the next time the same name is returned; otherwise the next available name is returned.
    The function ProMdlnameInit() does the opposite, and provides a valid ProMdl handle for a given name and type. The function fails if the specified model is not in memory in the Creo Parametric session.
    A third way to identify a model is by an integer identifier. Unlike the integer identifiers of objects within a model, such as surfaces and edges, the identifier of a model is not persistent between Creo Parametric sessions. The function ProMdlIdGet() provides the identifier of a model, given its ProMdl handle.
    The function ProMdlActiveGet() retrieves the model handle ProMdl for an active Creo Parametric object.
    The function ProMdlSubtypeGet() provides the subtype (such as sheet metal) of a specified model. Valid model subtypes are Part, Assembly, or Manufacturing. This is like finding subtypes at the Creo Parametric File ▶ New ▶ Model Type menu.
    The function ProMdlFiletypeGet() retrieves the file type of the specified model using the enumerated data type ProMdlfileType.
    The function ProFileSubtypeGet() retrieves the following information when you specify the path to a file as the input argument. The output arguments are:
    •  file_type—Specifies the file type using the enumerated data type ProMdlfileType. For native Creo models, the file type and model type are the same.
    •  type—Specifies the model type using the enumerated data type ProMdlType.
    •  subtype—Specifies the subtype of the model using the enumerated data type ProMdlsubtype. For model types that do not have subtypes, the argument returns PROMDLSTYPE_NONE.
    The function ProMdlToModelitem() is used only when you need to represent the model as a ProModelitem object—the first step in building a ProSelection object that describes the role of a model in a parent assembly. Model item objects are described later in this chapter. See the section Fundamentals for information on the ProSelection object.
    Example 1: Finding the Handle to a Model
    The following example shows how to find a model handle, given its name and type.
    ProName  name;
ProType  type;
ProMdl   part;
ProError status;
ProStringToWstring (name, "PRT0001");
type = PRO_PART;
status = ProMdlnameInit (name, type, &);
    Surface Properties of Models
    Functions Introduced:
  • ProMdlVisibleSideAppearancepropsGet()
    		•
  • ProMdlVisibleSideAppearancepropsSet()
    		•
  • ProMdlVisibleSideTexturepropsGet()
    		•
  • ProMdlVisibleSideTexturepropsSet()
    		•
  • ProMdlLockGet()
    		•
  • ProMdlLockSet()
    		•
  • ProMdlVisibleSideTextureplacementpropsGet()
    		•
  • ProMdlVisibleSideTextureplacementpropsSet()
    		•
    From Creo Parametric5.0.0.0 onwards, the following functions have been deprecated:
    •  ProMdlVisibleAppearancepropsGet()
    •  ProMdlVisibleAppearancepropsSet()
    •  ProMdlVisibleTexturepropsGet()
    •  ProMdlVisibleTexturepropsSet()
    •  ProMdlVisibleTextureplacementpropsGet()
    •  ProMdlVisibleTextureplacementpropsSet()
    The functions described in this section enable you to retrieve and set the surface and texture properties of models. You can retrieve and set these properties for any level in the model hierarchy. For assemblies, set the owner of ProModelitem as the top-level assembly. These properties may or may not be visible in the user interface depending on the properties set by the higher level assembly.
    Use the function ProMdlVisibleSideAppearancepropsGet() to retrieve the surface properties for a specified part, assembly component, subassembly, specified side of a quilt or surface using the ProSurfaceAppearanceProps data structure. Refer to the section Surface Properties, for more information on ProSurfaceAppearanceProps data structure. The input arguments are:
    •  item—Specifies a ProAsmitem object that represents the part, assembly component, subassembly, quilt, or surface.
    •  surface_side—Specifies the direction of the side for the surface or quilt. Pass the value as 0 to specify the side which is along the surface normal. Pass 1 to specify the side opposite to surface normal.
    Use the function ProMdlVisibleSideAppearancepropsSet() to set the surface properties for a specified element. To see the changes in the Creo Parametric user interface, call the function ProWindowRepaint() after ProMdlVisibleSideAppearancepropsSet(). To set the default surface appearance properties, pass the value of the input argument appearance_properties as NULL.
    Use the functions ProMdlVisibleSideTexturepropsGet() and ProMdlVisibleSideTexturepropsSet() to apply textures to the surface. These functions use the ProSurfaceTextureProps data structure to retrieve and set the texture properties of the surface for a specified element. Refer to the section Surface Properties, for more information on ProSurfaceTextureProps data structure.
    Use the functions ProMdlVisibleSideTextureplacementpropsGet() and ProMdlVisibleSideTextureplacementpropsSet() to retrieve and set the properties related to the placing of surface texture for the specified element. These functions use the ProSurfaceTexturePlacementProps data structure to define the placement properties.
    Refer to the section Surface Properties, for more information on ProSurfaceTexturePlacementProps data structure.
    The functions ProMdlLockGet() and ProMdlLockSet() get and set the lock/unlock state of the model. The function ProMdlLockGet() returns PRO_B_TRUE if the model is locked and PRO_B_FALSE if it is unlocked.
    The input arguments to the function ProMdlLockSet() follow:
    •  model—The model to be locked or unlocked.
    •  lock—Pass the value as PRO_B_TRUE to lock the model and PRO_B_FALSE to unlock it.
    Models in Session
    Functions Introduced:
  • ProSessionMdlList()
    		•
  • ProMdlCurrentGet()
    		•
  • ProMdlDependenciesDataList()
    		•
  • ProMdlDependenciesCleanup()
    		•
  • ProMdlDeclaredDataList()
    		•
  • ProMdlModificationVerify()
    		•
  • ProMdlVisibleModificationVerify()
    		•
  • ProMdlIsModifiable()
    		•
  • ProMdlIsEmbeddedName()
    		•
  • ProMdlVisibleGet()
    		•
    The function ProSessionMdlList() provides an array of ProMdl handles to models of a specified type currently in memory.
    The function ProMdlCurrentGet() provides the ProMdl handle to the model currently being edited by the user.
    The function ProMdlDependenciesDataList() provides an array of ProMdl handles to the models in memory upon which a specified model depends. One model depends on another if its contents reference that model in some way. For example, an assembly depends on the models that form its components, and a drawing model depends on the solid models contained in it. Sometimes, two models can be mutually dependent, such as when a model feature references a geometry item in a parent assembly. Clean the dependencies in the database using the function ProMdlDependenciesCleanup() to get an accurate list of dependencies for an object in the Creo Parametric workspace.
    Use the function ProMdlDependenciesCleanup() to clean the dependencies for an object in the Creo Parametric workspace.
    Note
    Do not call the function ProMdlDependenciesCleanup() during operations that alter the dependencies, such as, restructuring components and creating or redefining features.
    The function ProMdlDeclaredDataList() provides an array of ProMdl handles to first-level notebook models that have been declared to a specified solid model.
    The function ProMdlModificationVerify() tells you whether a specified model in memory has been modified since it was last saved or retrieved. See the section Version Stamps for a more flexible way of keeping track of changes to a model.
    The function ProMdlVisibleModificationVerify() checks if the visible model of the specified model has been modified since the last save. The input argument handle is used to verify the ProMdl object.
    The output argument p_modified returns PRO_B_TRUE if the model was modified and returns PRO_B_FALSE if the model was not modified.
    The function ProMdlIsModifiable() checks if the specified model is modifiable.
    The function ProMdlIsEmbeddedName() checks if the specified model name or full path that includes the model name is an embedded model name. The output argument is_embedded_name returns PRO_B_TRUE if the model name is an embedded name, PRO_B_FALSE if not.
    In intersected embedded components, the name of the embedded model cannot be used for file operations. If you are using the embedded name while creating a new application, the file operation might fail. In such case, you must use the generic or visible model name.
    The function ProMdlVisibleGet() returns the handle to the generic or visible model for the specified model. The function returns an error PRO_TK_E_NOT_FOUND, when the generic or visible model does not exist or is not found in the Creo Parametric session.
    When an embedded component is extracted, a copy of the embedded solid is created and the embedded component model is replaced by the new non-embedded copy. In this extract operation, the original embedded model is erased and the name of the model is changed.
    For embed operations, if a model has embedded components, a copy of the existing embedded models is created under the currently embedded model.
    File Management Operations
    Functions Introduced:
  • ProMdlnameCopy()
    		•
  • ProMdlfileMdlnameCopy()
    		•
  • ProMdlnameRetrieve()
    		•
  • ProMdlMultipleRetrieve()
    		•
  • ProSolidRetrievalErrorsGet()
    		•
  • ProMdlSave()
    		•
  • ProMdlIsSaveAllowed()
    		•
  • ProMdlErase()
    		•
  • ProMdlEraseNotDisplayed()
    		•
  • ProMdlEraseAll()
    		•
  • ProMdlnameRename()
    		•
  • ProMdlnameBackup()
    		•
  • ProMdlDelete()
    		•
  • ProMdlLocationIsStandard()
    		•
    These functions perform the same actions as the corresponding Creo Parametric file management commands, with the following exceptions:
    •  ProMdlnameCopy() and ProMdlfileMdlnameCopy() are equivalent to the Save As command in the File pull-down menu of the Creo Parametric menu bar. ProMdlnameCopy() takes the model handle as input, whereas ProMdlfileMdlnameCopy() takes the type and name of the model to copy.
    •  ProMdlnameRetrieve() retrieves the model into memory, but does not display it or make it the current model.
    •  ProMdlMultipleRetrieve() retrieves multiple models into memory. Use the ui_flag parameter to set model display to on or off.
    •  ProSolidRetrievalErrorsGet() returns the data structure containing errors that occur during model retrieval. While retrieving a complex assembly, Creo Parametric sometimes encounters errors in retrieving particular components and assembling them appropriately in the assembly. In the user interface, you are informed of errors as they occur, through a dialog box. In Creo TOOLKIT, the retrieval functions automatically suppress or freeze problem components and return PRO_TK_NO_ERROR. To know whether errors have occurred during retrieval, use the function ProSolidRetrievalErrorsGet(). The errors are returned as the elements of the ProSolidretrievalerrs array. The retrieval error information must be obtained immediately after a call to the ProMdlnameRetrieve() or equivalent retrieval function.
    •  ProMdlSave() saves the specified model to disk. For drawings, sketches and other 2D model types, to save the graphics data, you must display it. Call the function ProMdlDisplay() before ProMdlSave(), so that the graphics data is saved along with the geometry for the model.
    •  ProMdlIsSaveAllowed() checks whether a given model can be saved.
    •  ProMdlEraseNotDisplayed() erases all the models that are not referenced in a window from the current session.
    •  ProMdlErase() erases the specified model from memory.
    •  ProMdlEraseAll() erases a model and all the models that it uses, except those that have cyclic dependencies (that is, models used by other models in the session). For example, ProMdlEraseAll() recursively erases all subassemblies of an assembly and all solids referenced from a drawing. This function also works in cases where some models to be erased have mutual dependencies, but only if the erased models are not used by other models.
    However, while erasing an active model, ProMdlErase() and ProMdlEraseAll() only clear the graphic display immediately, they do not clear the data in the memory until the control returns to Creo Parametric from the Creo TOOLKIT application. Therefore, after calling them the control must be returned to Creo Parametric before calling any other function, otherwise the behavior of Creo Parametric may be unpredictable.
    The function ProMdlLocationIsStandard() checks if the specified model was opened from a standard location. A standard file location can be the local disk or a mapped drive on a remote computer. The Universal Naming Convention (UNC) path for network drives is also considered as a standard path if the value for DisableUNCCheck is set to True for the key HKEY_CURRENT_USER\Software\Microsoft\Command Processor, in the registry file. The function returns:
    •  PRO_B_TRUE when the file is loaded from a standard file location.
    •  PRO_B_FALSE when the file is loaded from a nonstandard file location, such as, http, ftp, Design Exploration mode, and so on.
    Model Items
    A “model item” is a generic object used to represent any item contained in any type of model, for the purpose of functions whose actions are applicable to all these types of item. (Some items, such as “version stamp,” retain their own object types.)
    The object type ProModelitem is a DHandle (data handle), a structure that contains the item type, the persistent integer identifier of the item, and the handle to the owning object.
    The object ProGeomitem, a generic geometrical object described later in this guide, is an instance of ProModelitem, and is a DHandle that shares the same type declaration. Therefore, the functions in this section are also directly applicable to ProGeomitem objects.
    The typedef for the ProModelitem data handle is as follows: 
         typedef struct pro_model_item
     {
       ProType   type;
       int       id;
       ProMdl    owner;
     } ProModelitem
    Functions Introduced:
  • ProModelitemByNameInit()
    		•
  • ProModelitemInit()
    		•
  • ProModelitemMdlGet()
    		•
  • ProModelitemDefaultnameGet()
    		•
  • ProModelitemNameGet()
    		•
  • ProModelitemNameSet()
    		•
  • ProModelitemNameCanChange()
    		•
  • ProModelitemUsernameDelete()
    		•
  • ProModelitemHide()
    		•
  • ProModelitemUnhide()
    		•
  • ProModelitemIsHidden()
    		•
    The function ProModelitemByNameInit() returns a pointer to an item (structure), given the name and the type of the item. The valid item types are:
    •  Edge
    •  Surface
    •  Feature
    •  Co-ordinate System
    •  Axis
    •  Point
    •  Quilt
    •  Curve
    •  Layer
    •  Note
    •  Combined State
    The function ProModelitemInit() is used to generate a ProModelitem object from the information contained in the structure. You can create such a structure directly, but using this function you can also confirm the existence of the item in the model database.
    The function ProModelitemMdlGet() extracts the ProMdl handle from the structure.
    The function ProModelitemDefaultnameGet() gets the default name for a new model item of a particular type if it was created taking the model handle as input.
    The two functions ProModelitemNameGet() and ProModelitemNameSet() read and set the name of the Creo Parametric database object referred to by the model item. These functions are therefore applicable to all the instances of ProModelitem, such as ProGeomitem and all its instances, including ProSurface, ProEdge, ProCsys, ProAxis, and ProCombinedState.
    Note
    In addition to notes of the type PRO_NOTE, the functions ProModelitemNameGet() and ProModelitemNameSet() can be used to read and set the name of the following annotation types:
    •  Driving or driven dimension of the type PRO_DIMENSION
    •  Reference dimension of the type PRO_REF_DIMENSION
    •  Symbol instance of the type PRO_SYMBOL_INSTANCE
    •  Surface finish of the type PRO_SURF_FIN
    •  Geometric tolerance of the type PRO_GTOL
    •  Set datum tag of the type PRO_SET_DATUM_TAG (applicable only for ProModelitemNameGet())
    The function ProModelitemNameCanChange() identifies whether the name of the model item can be modified by the user or by Creo TOOLKIT.
    The function ProModelitemUsernameDelete() deletes the user-defined name of the model item from the Creo Parametric database.
    The functions ProModelitemHide() and ProModelitemUnhide() are equivalent to the View ▶ Hide and View ▶ Unhide commands in the Creo Parametric menu, respectively. ProModelitemHide() hides the specified model item, whereas ProModelitemUnhide() unhides the model item.
    The function ProModelitemIsHidden() identifies if the specified model item is hidden.
    Example 2: Renaming a Selected Surface
    The sample code in UgGeomSurfRename.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_geometry shows how to use the functions ProModelitemNameGet() and ProModelitemNameSet(). See the Core: 3D Geometry chapter for an explanation of ProSurface and its functions.
    Version Stamps
    The version stamp object provides a way of keeping track of changes in a Creo Parametric model to which your Creo TOOLKIT application may need to respond. Creo Parametric models and features contain an internal version stamp incremented each time some design change is made to that model or feature. The functions in this section enable you to read version stamps in order to look for design changes.
    The version stamp object is called ProWVerstamp because it is a WHandle, or workspace handle. It is a workspace handle because the data structure it references is not the one in the Creo Parametric database, but a copy taken from it, which is private to the Creo TOOLKIT application.
    Functions Introduced:
  • ProMdlVerstampGet()
    		•
  • ProFeatureVerstampGet()
    		•
  • ProVerstampAlloc()
    		•
  • ProVerstampFree()
    		•
  • ProVerstampStringGet()
    		•
  • ProVerstampStringFree()
    		•
  • ProStringVerstampGet()
    		•
  • ProVerstampEqual()
    		•
    The functions ProMdlVerstampGet() and ProFeatureVerstampGet() enable you to make a workspace copy of the version stamp on a particular model or feature. The function ProMdlVerstampGet() is currently applicable to solids only (parts or assemblies). Both of these functions allocate the space for the workspace object internally. After using the contents of the version stamp object, you can free the workspace memory using ProVerstampFree().
    If you want to store a copy of a version stamp to compare to a newly read version later, you should use the nonvolatile representation, which is a C string. The function ProVerstampStringGet() allocates and fills a string that represents the contents of the specified ProWVerstamp object. The ProStringVerstampGet() function performs the reverse translation: it allocates a new ProWVerstamp object and fills it by copying the specified C string.
    The function ProVerstampEqual() compares two ProWVerstamp objects to tell you whether the version stamps they represent are equal.
    Note
    The version stamp on a feature can change not only when the feature definition changes, but also when the feature geometry changes as a result of a change to a parent feature.
    Layers
    Creo TOOLKIT implements two data types that enable access to layer information in Creo Parametric:
    •  ProLayer—A DHandle that identifies a layer. The ProLayer object is an instance of ProModelitem.
    •  ProLayerItem—A DHandle that identifies a layer item. The valid types of layer item are contained in the enumerated type ProLayerType.
    Functions Introduced:
  • ProMdlLayerGet()
    		•
  • ProMdlLayerVisit()
    		•
  • ProMdlLayersCollect()
    		•
  • ProLayerCreate()
    		•
  • ProLayerDelete()
    		•
  • ProLayerItemsGet()
    		•
  • ProLayerItemsPopulate()
    		•
  • ProLayeritemarrayFree()
    		•
  • ProLayerItemInit()
    		•
  • ProDwgLayerItemInit()
    		•
  • ProLayerSavedstatusGet()
    		•
  • ProLayerItemAdd()
    		•
  • ProLayerItemAddNoUpdate()
    		•
  • ProLayerItemRemove()
    		•
  • ProLayerItemRemoveNoUpdate()
    		•
  • ProLayeritemLayersGet()
    		•
  • ProLayerDisplaystatusGet()
    		•
  • ProLayerDisplaystatusSet()
    		•
  • ProLayerDisplaystatusNoUpdateSet()
    		•
  • ProLayerDisplaystatusUpdate()
    		•
  • ProDwgLayerDisplaystatusGet()
    		•
  • ProDwgLayerDisplaystatusSet()
    		•
  • ProDwgLayerSavedstatusGet
    		•
  • ProLayerDisplaystatusSave()
    		•
  • ProLayerDefLayerSet()
    		•
  • ProLayerDefLayerGet()
    		•
  • ProLayerViewDependencySet()
    		•
  • ProLayerViewDependencyGet()
    		•
  • ProLayerRuleExecute()
    		•
  • ProLayerRuleCopy()
    		•
  • ProLayerRuleMatch()
    		•
  • ProLayeritemLayerStatusGet()
    		•
    To get the ProLayer object for a layer with the specified name and owner, call the function ProMdlLayerGet(). You must pass the name of the layer as a wide string.
    To visit the layers in a model, use the function ProMdlLayerVisit(). As with other Creo TOOLKIT visit functions, you supply the visit action and visit filter functions.
    The function ProMdlLayersCollect() collects a ProArray of layers in the model.
    The function ProLayerCreate() creates a new layer with a specified name. It requires as input the ProMdl handle for the model that will own the layer. The function ProLayerDelete() deletes the layer identified by the specified ProLayer object.
    The function ProLayerItemsGet() allocates and fills an array of ProLayerItem objects that contains the items assigned to the specified layer.
    Note
    The function ProLayerItemsGet() is deprecated. For a large number of layer items, the function ProLayerItemsGet() may return an error PRO_TK_OUT_OF_MEMORY to indicate that the function was unable to allocate a ProArray to hold all of the layer items. To address this issue, use the new function ProLayerItemsPopulate().
    The function ProLayerItemsPopulate() allocates and fills an array of ProLayerItem objects that contain the type and identifier of the items assigned to the specified layer. This function can retrieve a large number of items specified on the layer. Use the function ProLayeritemarrayFree() to free the allocated memory.
    To initialize a ProLayerItem, call the function ProLayerItemInit(). This function should be used in all cases, except when all of the following are true:
    •  The layer owner is a drawing.
    •  The layer item owner is an assembly.
    •  The layer item is a component.
    •  You want to control the display status of this component only in a subassembly with a given path.
    When all of the above conditions are true, use the function ProDwgLayerItemInit() to initialize the ProLayerItem.
    The function ProLayerSavedstatusGet() retrieves the saved status for the specified layer. The output argument saved_status is defined by the enumerated data type ProLayerDisplay
    To add items to a layer, call the function ProLayerItemAdd(), and pass as input a ProLayer object and the ProLayeritem object for the new layer item. To remove an item from a layer, use the function ProLayerItemRemove() and specify the ProLayeritem object for the item to remove.
    The function ProLayerItemAddNoUpdate() adds the specified item to a layer without updating the model tree.
    The function ProLayerItemRemoveNoUpdate() removes the specified item from the layer without updating the model tree.
    To find all the layers containing a given layer item, use the function ProLayeritemLayersGet(). This function supports layers in solid models and in drawings.
    As in an interactive session of Creo Parametric, one of the principal reasons to create a layer is to display or blank its member items selectively. The function ProLayerDisplaystatusGet() obtains the display status of the specified layer, in the form of the ProLayerDisplay enumerated type. The display status can be of following types:
    •  PRO_LAYER_TYPE_NONE—The selected layer is displayed. This is the default display status.
    •  PRO_LAYER_TYPE_NORMAL—The layer selected by the user is displayed.
    •  PRO_LAYER_TYPE_DISPLAY—The selected layer is isolated.
    •  PRO_LAYER_TYPE_BLANK—The selected layer is blanked.
    •  PRO_LAYER_TYPE_HIDDEN—The components in the hidden layers are blanked. This status is applicable only in the assembly mode.
    To modify the display status of a layer, call the function ProLayerDisplaystatusSet().
    Note
    ProLayerDisplaystatusSet() does not repaint the model after it modifies the display status. This is a temporary setting. It will be lost after you save or retrieve the model. To permanently change the display status, call the function ProLayerDisplaystatusSave(). However, the function ProLayerDisplaystatusSet() updates the model tree for the change in display status of the layer.
    The function ProLayerDisplaystatusNoUpdateSet() sets the display status of a layer, without updating the model tree. It returns a boolean value PRO_B_TRUE for the output argument is_update_tree_needed, if the model tree requires an update for change in the display status of a layer. Use the function ProLayerDisplaystatusUpdate() to update the model tree for all the changes in the display statuses of all the layers in the specified model.
    Unique functions are required to retrieve and set the status of layers in drawings. ProDwgLayerDisplaystatusGet() takes as input the layer handle and drawing view. The function ProDwgLayerDisplaystatusSet() takes an additional argument as input—the desired display status.
    Use the function ProDwgLayerSavedstatusGet() to retrieve the saved status for the specified layer and view.
    •  layer —The layer for which you want to retrieve the status .
    •  view —The view of drawing for which you want to retrieve the status.
    The function ProLayerDisplaystatusSave() saves the changes to the display status of all the layers in the specified owner. In addition, the display statuses are saved in the owner's submodels and drawing views.
    To set up a default layer with a specified name, call the function ProLayerDefLayerSet(). This function requires the default layer type, which is defined in the enumerated type ProDefLayerType. To get the name of the default layer with the specified type, call the function ProLayerDefLayerGet().
    The function ProLayerViewDependencySet() sets the display of layers of the specified view to depend on the display of layers in the drawing. The syntax of this function is as follows: 
    ProLayerViewDependencySet (

  ProView      view, 
  ProBoolean   depend);
    If depend is set to PRO_B_TRUE, the layers in the view will be displayed when the layers in the drawing are displayed. If depend is set to PRO_B_FALSE, the layer display in the view will be independent of the display in the drawing. To determine whether the layer display in the view is dependent on the display in the drawing, call the function ProLayerViewDependencyGet().
    You can define rules in layers. Use the function ProLayerRuleExecute() to execute the layer rules on the specified model. The rules must be enabled in the layers to be executed.
    The function ProLayerRuleCopy() copies the rules from the reference model to the current model for the specified layer. The input arguments are:
    •  CurrentModel—Specifies the current model to which the layer rules must be copied.
    •  LayerName—Specifies the name of an existing layer in both the models. To copy the layer rules, the name of the layer LayerName in both the models must be the same.
    •  ReferenceModel—Specifies the reference model from which the layer rules must be copied.
    Use the function ProLayerRuleMatch() to compare the rules between the current and reference model for the specified layer. The name of the layer LayerName in both the models must be the same, for comparing the layer rules.
    The function ProLayeritemLayerStatusGet() returns the status of an item for the specified layer. The input arguments are:
    •  pro_drawing—Specifies the drawing which is the owner of the layer that contains the specified item.
    •  pro_layer_item—Specifies the layer item. If the owner type of the layer item is PRO_LAYITEM_FROM_PATH, it is mandatory to specify the pro_drawing input argument.
    •  pro_layer—Specifies the layer that contains the item.
    The output argument returns the status of the item using the enumerated data type ProLayerItemStatus. The valid values are:
    •  PRO_LAY_ITEM_STATUS_INCLUDE—Specifies that the status of the layer item is Include. The item is included in the specified layer.
    •  PRO_LAY_ITEM_STATUS_EXCLUDE—Specifies that the status of the layer item is Exclude. The item is excluded in the specified layer.
    •  PRO_LAY_ITEM_STATUS_ADDED_BY_RULE—Specifies that the status of the layer item is defined by rules.
    The enumerated data type ProLayerItemStatus must have one of the following values:
    •  PRO_LAY_ITEM_STATUS_INCLUDE
    •  PRO_LAY_ITEM_STATUS_EXCLUDE
    •  PRO_LAY_ITEM_STATUS_INCLUDE and PRO_LAY_ITEM_STATUS_ADDED_BY_RULE
    •  PRO_LAY_ITEM_STATUS_EXCLUDE and PRO_LAY_ITEM_STATUS_ADDED_BY_RULE
    Example 3: Creating a Layer
    The sample code in UgModelLayerCreate.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_model shows how to create a layer and add items to it.
    This example streamlines the layer creation process (compared to interactive Creo Parametric) because the application creates the layer and adds items to it in only one step. Note that this example does not allow users to add a subassembly to the new layer.
    Notebook
    The functions described in this section work with notebook (.lay) files.
    Functions Introduced:
  • ProLayoutDeclare()
    		•
  • ProLayoutUndeclare()
    		•
  • ProLayoutRegenerate()
    		•
    The function ProLayoutDeclare() declares a notebook name to the specified Creo Parametric model or notebook. You can resolve conflicts using the enumerated type ProDeclareOptions. It has the following values:
    •  PRO_DECLARE_INTERACTIVE—Resolves the conflict in interactive mode.
    •  PRO_DECLARE_OBJECT_SYMBOLS—Keep the symbols in the specified Creo Parametric model or notebook object.
    •  PRO_DECLARE_LAYOUT_SYMBOLS—Keep the symbols specified in the notebook.
    •  PRO_DECLARE_ABORT—Abort the notebook declaration process and return an error.
    Use the function ProLayoutUndeclare() to undeclare the notebook name to the specified Creo Parametric model or notebook. You can resolve conflicts using the enumerated type ProUndeclareOptions. It has the following values:
    •  PRO_UNDECLARE_FORCE—Continues to undeclare the notebook even if references exist.
    •  PRO_UNDECLARE_CANCEL—Does not undeclare the notebook if references exist.
    The method ProLayoutRegenerate() regenerates the specified notebook.
    Visiting Displayed Entities
    Functions Introduced:
  • ProSolidDispCompVisit()
    		•
  • ProAsmcomppathDispPointVisit()
    		•
  • ProAsmcomppathDispCurveVisit()
    		•
  • ProAsmcomppathDispCsysVisit()
    		•
  • ProAsmcomppathDispQuiltVisit()
    		•
    The functions in this section enable you to find quickly all the entities (points, datum curves, coordinate systems, and quilts) currently displayed in an assembly. It is possible to do this using the regular Creo TOOLKIT functions for visiting assembly components and entities, together with the ProLayer functions explained earlier in this chapter; but the functions described here are much more efficient because they make use of Creo Parametric's internal knowledge of the display structures.
    The function ProSolidDispCompVisit() traverses the components at all levels in an assembly which are not blanked by a layer. The visit action function is called on both the downward traversal and the upward one, and is given a boolean input to distinguish them. It is also given the assembly path and the solid handle to the current subassembly. The subassembly could be found from the path using ProAsmcomppathMdlGet(), of course, but Creo Parametric passes this to the action function to allow greater efficiency.
    The functions ProAsmcomppathDisp*Visit() visit the entities in a subassembly that are not blanked by a layer at any level in the root assembly.