Models
This section describes how to program on the model level using Creo Object TOOLKIT C++.
Overview of Model Objects
Models can be any Creo file type, including parts, assemblies, drawings, sections, and notebook. The classes and methods in pfcModel provide generic access to models, regardless of their type. The available methods enable you to do the following:
•  Access information about a model.
•  Open, copy, rename, and save a model.
Getting a Model Object
Methods Introduced:
  • pfcFamilyTableRow::CreateInstance
    		•
  • pfcSelection::GetSelModel
    		•
  • pfcBaseSession::GetModel
    		•
  • pfcBaseSession::GetCurrentModel
    		•
  • pfcBaseSession::GetActiveModel
    		•
  • pfcBaseSession::ListModels
    		•
  • pfcBaseSession::GetByRelationId
    		•
  • pfcWindow::GetModel
    		•
    These methods get a model object that is already in session.
    The method pfcSelection::GetSelModel returns the model that was interactively selected.
    The method pfcBaseSession::GetModel returns a model based on its name and type, whereas pfcBaseSession::GetByRelationId returns a model in an assembly that has the specified integer identifier.
    The method pfcBaseSession::GetCurrentModel returns the current active model.
    The method pfcBaseSession::GetActiveModel returns the active Creo model.
    Use the method pfcBaseSession::ListModels to return a sequence of all the models in session.
    For more methods that return solid models, refer to the section Solid.
    Model Descriptors
    Methods Introduced:
  • pfcModelDescriptor::Create
    		•
  • pfcModelDescriptor::CreateFromFileName
    		•
  • pfcModelDescriptor::SetGenericName
    		•
  • pfcModelDescriptor::SetInstanceName
    		•
  • pfcModelDescriptor::SetType
    		•
  • pfcModelDescriptor::SetDevice
    		•
  • pfcModelDescriptor::SetPath
    		•
  • pfcModelDescriptor::SetFileVersion
    		•
  • pfcModelDescriptor::GetFullName
    		•
  • pfcModel::GetFullName
    		•
    Model descriptors are data objects used to describe a model file and its location in the system. The methods in the model descriptor enable you to set specific information that enables the Creo application to find the specific model you want.
    The static utility method pfcModelDescriptor::Create allows you to specify as data to be entered a model type, an instance name, and a generic name. The model descriptor constructs the full name of the model as a string, as follows: 
    xstring FullName = InstanceName+"<"+GenericName+">";  
                                    // As long as the
                                    // generic name is
                                    // not an empty 
                                    // string ("")
    If you want to load a model that is not a family table instance, pass an empty string as the generic name argument so that the full name of the model is constructed correctly. If the model is a family table interface, you should specify both the instance and generic names.
    Note
    You are allowed to set other fields in the model descriptor object, but they may be ignored by some methods.
    The static utility method pfcModelDescriptor::CreateFromFileName allows you to create a new model descriptor from a given a file name. The file name is a string in the form <name>.<extension>.
    Retrieving Models
    Methods Introduced:
  • pfcBaseSession::RetrieveModel
    		•
  • pfcBaseSession::RetrieveModelWithOpts
    		•
  • pfcBaseSession::OpenFile
    		•
  • pfcSolid::HasRetrievalErrors
    		•
    These methods enable Creo to retrieve the model that corresponds to the pfcModelDescriptor argument.
    The method pfcBaseSession::RetrieveModel retrieves the specified model into the Creo session given its model descriptor from a standard directory. This method ignores the path argument specified in the model descriptor. But this function does not create a window for it, nor does it display the model anywhere.
    The method pfcBaseSession::RetrieveModelWithOpts retrieves the specified model into the Creo session based on the path specified by the model descriptor. The path can be a disk path, a workspace path, or a commonspace path. The Opts argument (given by the pfcRetrieveModelOptions object) provides the user with the option to specify simplified representations.
    The method pfcBaseSession::OpenFile brings the model into memory, opens a new window for it (or uses the base window, if it is empty), and displays the model.
    Note
    pfcBaseSession::OpenFile actually returns a handle to the window it has created.
    The file version set by the pfcModelDescriptor::SetFileVersion method is ignored by the pfcBaseSession::RetrieveModelWithOpts and pfcBaseSession::OpenFile methods. Instead, the latest file version of the model is used by these two methods.
    To get a handle to the model you need, use the method pfcWindow::GetModel.
    The method pfcSolid::HasRetrievalErrors returns a true value if the features in the solid model were suppressed during the RetrieveModel or OpenFile operations. This method must be called immediately after the pfcBaseSession::RetrieveModel method or an equivalent retrieval method.
    Model Information
    Methods Introduced:
  • pfcModel::IsNativeModel
    		•
  • pfcModel::GetFileName
    		•
  • pfcModel::GetCommonName
    		•
  • pfcModel::IsCommonNameModifiable
    		•
  • pfcModel::GetFullName
    		•
  • pfcModel::GetGenericName
    		•
  • pfcModel::GetInstanceName
    		•
  • wfcWModel::GetDefaultName
    		•
  • pfcModel::GetOrigin
    		•
  • pfcModel::GetRelationId
    		•
  • pfcModel::GetDescr
    		•
  • pfcModel::GetType
    		•
  • pfcModel::GetIsModified
    		•
  • pfcModel::GetVersion
    		•
  • pfcModel::GetRevision
    		•
  • pfcModel::GetBranch
    		•
  • pfcModel::GetReleaseLevel
    		•
  • pfcModel::GetVersionStamp
    		•
  • pfcModel::ListDependencies
    		•
  • pfcModel::CleanupDependencies
    		•
  • pfcModel::ListDeclaredModels
    		•
  • pfcModel::CheckIsModifiable
    		•
  • pfcModel::CheckIsSaveAllowed
    		•
  • wfcWModel::GetSubType
    		•
    The method pfcModel::IsNativeModel returns true, if the specified model is a native Creo model. It returns false, when the model is a non-native part or assembly created in other CAD applications.
    The method pfcModel::GetFileName retrieves the model file name in the "name"."type" format.
    The method pfcModel::GetCommonName retrieves the common name for the model. This name is displayed for the model in Windchill PDMLink.
    Use the method pfcModel::GetIsCommonNameModifiable to identify if the common name of the model can be modified. You can modify the name 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 method pfcModel::GetFullName retrieves the full name of the model in the instance <generic> format.
    The method pfcModel::GetGenericName retrieves the name of the generic model. If the model is not an instance, this name must be NULL or an empty string.
    The method pfcModel::GetInstanceName retrieves the name of the model. If the model is an instance, this method retrieves the instance name.
    The method wfcWModel::GetDefaultName gets the default name assigned to the model by Creo application at the time of creation.
    The method pfcModel::GetOrigin returns the complete path to the file from which the model was opened. This path can be a location on disk from a Windchill workspace, or from a downloaded URL.
    The method pfcModel::GetRelationId retrieves the relation identifier of the specified model. It can be NULL.
    The method pfcModel::GetDescr returns the descriptor for the specified model. Model descriptors can be used to represent models not currently in session.
    Note
    The methods pfcModel::GetFullName, pfcModel::GetGenericName, and pfcModel::GetDescr throw an exception pfcXtoolkitCantOpen if called on a model instance whose immediate generic is not in session. Handle this exception and typecast the model as pfcSolid, which in turn can be typecast as pfcFamilyMember, and use the method pfcFamilyMember::GetImmediateGenericInfo to get the model descriptor of the immediate generic model. The model descriptor can be used to derive the full name or generic name of the model.
    If you wish to switch this behavior to the pre-Wildfire 4.0 mode, set the configuration option retrieve_instance_dependencies to instance_and_generic_deps.
    The method pfcModel::GetType returns the type of model in the form of the pfcModelType object. The types of models are as follows:
    •  pfcMDL_ASSEMBLY—Specifies an assembly.
    •  pfcMDL_PART—Specifies a part.
    •  pfcMDL_DRAWING—Specifies a drawing.
    •  pfcMDL_2D_SECTION—Specifies a 2D section.
    •  pfcMDL_LAYOUT—Specifies a notebook.
    •  pfcMDL_DWG_FORMAT—Specifies a drawing format.
    •  pfcMDL_MFG—Specifies a manufacturing model.
    •  pfcMDL_REPORT—Specifies a report.
    •  pfcMDL_MARKUP—Specifies a drawing markup.
    •  pfcMDL_DIAGRAM—Specifies a diagram
    •  pfcMDL_CE_SOLID—Specifies a Layout model.
    Note
    Creo Object TOOLKIT C++ methods will only be able to read models of type Layout, but will not be able to pass Layout models as input to other methods. PTC recommends that you review all Creo Object TOOLKIT C++ applications that use the enumerated type pfcModelType and modify the code as appropriate to ensure that the applications work correctly.
    The method pfcModel::GetIsModified identifies whether the model has been modified since it was last saved.
    The method pfcModel::GetVersion returns the version of the specified model from the PDM system. It can be NULL, if not set.
    The method pfcModel::GetRevision returns the revision number of the specified model from the PDM system. It can be NULL, if not set.
    The method pfcModel::GetBranch returns the branch of the specified model from the PDM system. It can be NULL, if not set.
    The method pfcModel::GetReleaseLevel returns the release level of the specified model from the PDM system. It can be NULL, if not set.
    The method pfcModel::GetVersionStamp returns the version stamp of the specified model. The version stamp is a Creo specific identifier that changes with each change made to the model.
    The method pfcModel::ListDependencies returns a list of the first-level dependencies for the specified model in the Creo workspace in the form of the pfcDependencies object.
    Use the method pfcModel::CleanupDependencies to clean the dependencies for an object in the Creo workspace.
    Note
    Do not call the method pfcModel::CleanupDependencies during operations that alter the dependencies, such as, restructuring components and creating or redefining features.
    The method pfcModel::ListDeclaredModels returns a list of all the first-level objects declared for the specified model.
    The method pfcModel::CheckIsModifiable identifies if a given model can be modified without checking for any subordinate models. This method takes a boolean argument ShowUI that determines whether the Creo conflict resolution dialog box should be displayed to resolve conflicts, if detected. If this argument is false, then the conflict resolution dialog box is not displayed, and the model can be modified only if there are no conflicts that cannot be overridden, or are resolved by default resolution actions. For a generic model, if ShowUI is true, then all instances of the model are also checked.
    The method pfcModel::CheckIsSaveAllowed identifies if a given model can be saved along with all of its subordinate models. The subordinate models can be saved based on their modification status and the value of the configuration option save_objects. This method also checks the current user interface context to identify if it is currently safe to save the model. Thus, calling this method at different times might return different results. This method takes a boolean argument ShowUI. Refer to the previous method for more information on this argument.
    The method wfcWModel::GetSubType returns the subtype of the specified model using the enumerated data type wfcModelSubType. This is similar to selecting types and sub-types of models available in the Creo user interface using the command File ▶ New.
    Model Operations
    Methods Introduced:
  • pfcModel::Backup
    		•
  • pfcModel::Copy
    		•
  • pfcModel::CopyAndRetrieve
    		•
  • pfcModel::Rename
    		•
  • pfcModel::Save
    		•
  • pfcModel::Erase
    		•
  • pfcModel::EraseWithDependencies
    		•
  • pfcModel::Delete
    		•
  • pfcModel::Display
    		•
  • pfcModel::SetCommonName
    		•
  • wfcWModel::IsStandardLocation
    		•
    These model operations duplicate most of the commands available in the Creo File menu.
    The method pfcModel::Backup makes a backup of an object in memory to a disk in a specified directory.
    The method pfcModel::Copy copies the specified model to another file.
    The method pfcModel::CopyAndRetrieve copies the model to another name, and retrieves that new model into session.
    The method pfcModel::Rename renames a specified model.
    The method pfcModel::Save stores the specified model to a disk.
    The method pfcModel::Erase erases the specified model from the session. Models used by other models cannot be erased until the models dependent upon them are erased.
    The method pfcModel::EraseWithDependencies erases the specified model from the session and all the models on which the specified model depends from disk, if the dependencies are not needed by other items in session.
    Note
    However, while erasing an active model, pfcModel::Erase and pfcModel::EraseWithDependencies only clear the graphic display immediately, they do not clear the data in the memory until the control returns to Creo application from the Creo Object TOOLKIT C++ application. Therefore, after calling them the control must be returned to Creo before calling any other function, otherwise the behavior of Creo may be unpredictable.
    The method pfcModel::Delete removes the specified model from memory and disk.
    The method pfcModel::Display displays the specified model. You must call this method if you create a new window for a model because the model will not be displayed in the window until you call pfcDisplay.
    The method pfcModel::SetCommonName modifies the common name of the specified model. You can modify this name 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 method wfcWModel::IsStandardLocation 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 method returns:
    •  True when the file is loaded from a standard file location.
    •  False when the file is loaded from a nonstandard file location, such as, http, ftp, Design Exploration mode, and so on.
    Running Creo Modelcheck
    Creo ModelCHECK is an integrated application that runs transparently within Creo Parametric. It uses a configurable list of company design standards and best modeling practices. You can configure Creo ModelCHECK to run interactively or automatically when you regenerate or save a model.
    Methods Introduced:
  • pfcBaseSession::ExecuteModelCheck
    		•
  • pfcModelCheckInstructions::Create
    		•
  • pfcModelCheckInstructions::SetConfigDir
    		•
  • pfcModelCheckInstructions::SetMode
    		•
  • pfcModelCheckInstructions::SetOutputDir
    		•
  • pfcModelCheckInstructions::SetShowInBrowser
    		•
  • pfcModelCheckResults::GetNumberOfErrors
    		•
  • pfcModelCheckResults::GetNumberOfWarnings
    		•
  • pfcModelCheckResults::GetWasModelSaved
    		•
    You can run Creo ModelCHECK from an external application using the method pfcBaseSession::ExecuteModelCheck. This method takes the model Model on which you want to run Creo ModelCHECK and instructions in the form of the object ModelCheckInstructions as its input parameters. This object contains the following parameters:
    •  ConfigDir—Specifies the location of the configuration files. If this parameter is set to NULL, the default Creo ModelCHECK configuration files are used.
    •  Mode—Specifies the mode in which you want to run Creo ModelCHECK. The modes are:
    ○  MODELCHECK_GRAPHICS—Interactive mode
    ○  MODELCHECK_NO_GRAPHICS—Batch mode
    •  OutputDir—Specifies the location for the reports. If you set this parameter to NULL, the default Creo ModelCHECK directory, as per config_init.mc, will be used.
    •  ShowInBrowser—Specifies if the results report should be displayed in the Web browser.
    The method pfcModelCheckInstructions::Create creates the pfcModelCheckInstructions object containing the Creo ModelCHECK instructions described above.
    Use the methods pfcModelCheckInstructions::SetConfigDir, pfcModelCheckInstructions::SetMode, pfcModelCheckInstructions::SetOutputDir, and pfcModelCheckInstructions::SetShowInBrowser to modify the Creo ModelCHECK instructions.
    The method pfcBaseSession::ExecuteModelCheck returns the results of the Creo ModelCHECK run in the form of the pfcModelCheckResults object. This object contains the following parameters:
    •  NumberOfErrors—Specifies the number of errors detected.
    •  NumberOfWarnings—Specifies the number of warnings found.
    •  WasModelSaved—Specifies whether the model is saved with updates.
    Use the methods pfcModelCheckResults::GetNumberOfErrors, pfcModelCheckResults::GetNumberOfWarning, and pfcModelCheckResults::GetWasModelSaved to access the results obtained.
    Custom Checks
    This section describes how to define custom checks in ModelCHECK that users can run using the standard Creo ModelCHECK interface in Creo Parametric.
    To define and register a custom check:
    1. Set the CUSTMTK_CHECKS_FILE configuration option in the start configuration file to a text file that stores the check definition. For example: CUSTMTK_CHECKS_FILE text\custmtk_checks.txt.
    2. Set the contents of the CUSTMTK_CHECKS_FILE file to define the checks. Each check should list the following items:
    •  DEF_<checkname>—Specifies the name of the check. The format must be CHKTK_<checkname>_<mode>, where mode is PRT, ASM, or DRW.
    •  TAB_<checkname>—Specifies the tab category in the Creo ModelCHECK report under which the check is classified. Valid tab values are:
    ○  INFO
    ○  PARAMETER
    ○  LAYER
    ○  FEATURE
    ○  RELATION
    ○  DATUM
    ○  MISC
    ○  VDA
    ○  VIEWS
    •  MSG_<checkname>—Specifies the description of the check that appears in the lower part of the Creo ModelCHECK report when you select the name.
    •  DSC_<checkname>—Specifies the name of the check as it appears in the Creo ModelCHECK report table.
    •  ERM_<checkname>—If set to INFO, the check is considered an INFO check and the report table displays the text from the first item returned by the check, instead of a count of the items. Otherwise, this value must be included, but is ignored by Creo Parametric.
    3. Add the check and its values to the Creo ModelCHECK configuration file.
    4. Register the Creo ModelCHECK check from the Creo Object TOOLKIT C++ application.
    Note
    Other than the requirements listed above, Creo Object TOOLKIT C++ custom checks do not have access to the rest of the values in the Creo ModelCHECK configuration files. All the custom settings specific to the check, such as start parameters, constants, and so on, must be supported by the user application and not Creo ModelCHECK.
    Registering Custom Checks
    Methods Introduced:
  • pfcBaseSession::RegisterCustomModelCheck
    		•
  • pfcCustomCheckInstructions::Create
    		•
  • pfcCustomCheckInstructions::SetCheckName
    		•
  • pfcCustomCheckInstructions::SetCheckLabel
    		•
  • pfcCustomCheckInstructions::SetListener
    		•
  • pfcCustomCheckInstructions::SetActionButtonLabel
    		•
  • pfcCustomCheckInstructions::SetUpdateButtonLabel
    		•
    The method pfcBaseSession::RegisterCustomModelCheck registers a custom check that can be included in any Creo ModelCHECK run. This method takes the instructions in the form of the pfcCustomCheckInstructions object as its input argument. This object contains the following parameters:
    •  CheckName—Specifies the name of the custom check.
    •  CheckLabel—Specifies the label of the custom check.
    •  Listener—Specifies the listener object containing the custom check methods. Refer to the section Custom Check Listeners for more information.
    •  ActionButtonLabel—Specifies the label for the action button. If you specify NULL for this parameter, this button is not shown.
    •  UpdateButtonLabel—Specifies the label for the update button. If you specify NULL for this parameter, this button is not shown.
    The method pfcCustomCheckInstructions::Create creates the pfcCustomCheckInstructions object containing the custom check instructions described above.
    Use the methods pfcCustomCheckInstructions::SetCheckName, pfcCustomCheckInstructions::SetCheckLabel, pfcCustomCheckInstructions::SetListener, pfcCustomCheckInstructions::SetActionButtonLabel, and pfcCustomCheckInstructions::SetUpdateButtonLabel to modify the instructions.
    The following figure illustrates how the results of some custom checks might be displayed in the Creo ModelCHECK report.
    Image
    Custom Check Listeners
    Methods Introduced:
  • pfcModelCheckCustomCheckListener::OnCustomCheck
    		•
  • pfcModelCheckCustomCheckListener::OnCustomCheckAction
    		•
  • pfcModelCheckCustomCheckListener::OnCustomCheckUpdate
    		•
  • pfcCustomCheckResults::Create
    		•
  • pfcCustomCheckResults::SetResultsCount
    		•
  • pfcCustomCheckResults::SetResultsTable
    		•
  • pfcCustomCheckResults::SetResultsUrl
    		•
    The interface pfcModelCheckCustomCheckListener provides the method signatures to implement a custom Creo ModelCHECK check.
    Each listener method takes the following input arguments:
    •  CheckName—The name of the custom check as defined in the original call to the method pfcBaseSession::RegisterCustomModelCheck
    •  Mdl—The model being checked.
    The application method that overrides pfcModelCheckCustomCheckListener::OnCustomCheck is used to evaluate a custom defined check. The user application runs the check on the specified model and returns the results in the form of the CustomCheckResults object.
    •  ResultsCount—Specifies an integer indicating the number of errors found by the check. This value is displayed in the Creo ModelCHECK report generated.
    •  ResultsTable—Specifies a list of text descriptions of the problem encountered for each error or warning.
    •  ResultsUrl—Specifies the link to an application-owned page that provides information on the results of the custom check.
    The method pfcCustomCheckResults::Create creates the pfcCustomCheckResults object containing the custom check results described above.
    Use the methods pfcCustomCheckResults.SetResultsCount, pfcCustomCheckResults::SetResultsTable, and pfcCustomCheckResults::SetResultsUrl listed above to modify the custom checks results obtained.
    The method that overrides pfcModelCheckCustomCheckListener::OnCustomCheckAction is called when the custom check’s Action button is pressed. The input supplied includes the text selected by the user from the custom check results.
    The function that overrides pfcModelCheckCustomCheckListener::OnCustomCheckUpdate is called when the custom check’s Update button is pressed. The input supplied includes the text selected by the user from the custom check results.
    Custom Creo ModelCHECK checks can have an Action button to highlight the problem, and possibly an Update button to fix it automatically.
    The following figure displays the Creo ModelCHECK report with an Action button that invokes the pfcModelCheckCustomCheckListener::OnCustomCheckAction
    Image
    Notebook
    The methods described in this section work with notebook (.lay) files.
    Methods introduced:
  • wfcWLayout::Declare
    		•
  • wfcWLayout::Undeclare
    		•
    The method wfcWLayout::Declare declares a notebook name to the specified Creo Parametric model or notebook. You can resolve conflicts using the enumerated type wfcLayoutDeclareOption. It has the following values:
    •  wfcLAYOUT_DECLARE_INTERACTIVE— Resolves the conflict in interactive mode.
    •  wfcLAYOUT_DECLARE_OBJECT_SYMBOLS— Keep the symbols in the specified Creo Parametric model or notebook object.
    •  wfcLAYOUT_DECLARE_LAYOUT_SYMBOLS — Keep the symbols specified in the notebook.
    •  wfcLAYOUT_DECLARE_ABORT— abort the notebook declaration process and return an error.
    Use the function wfcWLayout::Undeclare to undeclare the notebook name to the specified Creo Parametric model or notebook. You can resolve conflicts using the enumerated type wfcLayoutUndeclareOption. It has the following values:
    •  wfcLAYOUT_UNDECLARE_FORCE— Continues to undeclare the notebook even if references exist.
    •  wfcLAYOUT_UNDECLARE_CANCEL— Does not undeclare the notebook if references exist.