Action Listeners
This section describes the Creo Object TOOLKIT C++ methods that enable you to use action listeners.
Creo Object TOOLKIT C++ Action Listeners
An ActionListener in Creo Object TOOLKIT C++ is a class that is assigned to respond to certain events. You can assign action listeners to respond to events involving the following tasks:
•  Changing windows
•  Changing working directories
•  Model operations
•  Regenerating
•  Creating, deleting, and redefining features
•  Checking for regeneration failures
All action listeners in Creo Object TOOLKIT C++ are defined by a named pfc<Object>ActionListener. This interface defines the methods that can respond to various events.
Besides, for some listeners a default implementation class is provided, named pfcDefault<Object>ActionListener. This class has every available method overridden by an empty implementation. You create your own action listeners by extending the default class and overriding the methods for events that interest you. Default implementations are provided for the following listeners:
•  pfcFeatureActionListener
•  pfcSolidActionListener
•  pfcSessionActionListener
•  pfcModelEventActionListener
•  pfcModelActionListener
Note
When notifications are set in Creo Object TOOLKIT C++ applications, every time an event is triggered, notification messages are added to the trail files. From Creo Parametric 2.0 M210 onward, a new environment variable PROTK_LOG_DISABLE enables you to disable this behavior. When set to true, the notifications messages are not added to the trail files.
Creating an ActionListener Implementation
You can create a proper ActionListener class using either of the following methods:
Define a separate class within the Creo Object TOOLKIT C++ file.
To use your action listener in different applications, define it in a separate file.
Action Sources
Methods introduced:
  • pfcActionSource::AddActionListener
    		•
  • pfcActionSource::AddActionListenerWithType
    		•
  • pfcActionSource::RemoveActionListener
    		•
    Many Creo Object TOOLKIT C++ classes inherit the pfcActionSource interface, but only the following classes currently make calls to the methods of registered ActionListeners:
    •  pfcSession
    ○  Session Action Listener
    ○  Model Action Listener
    ○  Solid Action Listener
    ○  Model Event Action Listener
    ○  Feature Action Listener
    •  pfcUICommand
    ○  UI Action Listener
    •  pfcModel (and it’s subclasses)
    ○  Model Action Listener
    ○  Parameter Action Listener
    •  pfcSolid (and it’s subclasses)
    ○  Solid Action Listener
    ○  Feature Action Listener
    •  pfcFeature (and it’s subclasses)
    ○  Feature Action Listener
    Note
    ○  Assigning an action listener to a source not related to it will not cause an error but the listener method will never be called.
    ○  It is recommended to use smart pointer to create an instance of pfc Action Listener class. The smart pointer can be destroyed by calling the pfcActionSource::RemoveActionListener method. The keyword delete is not required to delete the smart pointer.
    ○  The method pfcActionSource::AddActionListener adds action listeners to notify you of all the events.
    ○  The method pfcActionSource::AddActionListenerWithType adds action listeners to notify you about events that are specified in the input argument ATypes.
    Types of Action Listeners
    The following sections describe the different kinds of action listeners: session, UI command, solid, and feature.
    Dimension Level Action Listeners
    Methods Introduced:
  • wfcDimensionActionListener::OnBeforeDimensionValueModify
    		•
    The method wfcDimensionActionListener::OnBeforeDimensionValueModify is called before the dimension value is modified.
    Session Level Action Listeners
    Methods introduced:
  • pfcSessionActionListener::OnAfterDirectoryChange
    		•
  • pfcSessionActionListener::OnAfterWindowChange
    		•
  • pfcSessionActionListener::OnAfterModelDisplay
    		•
  • pfcSessionActionListener::OnBeforeModelErase
    		•
  • pfcSessionActionListener::OnBeforeModelDelete
    		•
  • pfcSessionActionListener::OnBeforeModelRename
    		•
  • pfcSessionActionListener::OnBeforeModelSave
    		•
  • pfcSessionActionListener::OnBeforeModelPurge
    		•
  • pfcSessionActionListener::OnBeforeModelCopy
    		•
  • pfcSessionActionListener::OnAfterModelPurge
    		•
  • wfcWSession::AddBrowserMessageListener
    		•
    The pfcSessionActionListener::OnAfterDirectoryChange method activates after the user changes the working directory. This method takes the new directory path as an argument.
    The pfcSessionActionListener::OnAfterWindowChange method activates when the user activates a window other than the current one. Pass the new window to the method as an argument.
    The pfcSessionActionListener::OnAfterModelDisplay method activates every time a model is displayed in a window.
    Note
    Model display events happen when windows are moved, opened and closed, repainted, or the model is regenerated. The event can occur more than once in succession.
    The methods pfcSessionActionListener::OnBeforeModelErase, pfcSessionActionListener::OnBeforeModelRename, pfcSessionActionListener::OnBeforeModelSave, and pfcSessionActionListener::OnBeforeModelCopy take special arguments. They are designed to allow you to fill in the arguments and pass this data back to Creo Parametric. The model names placed in the descriptors will be used by Creo Parametric as the default names in the user interface.
    The method wfcWSession::AddBrowserMessageListener adds a listener callback to receive browser message with specified key. The input arguments are:
    •  key—Unique key that should be specified in the Java Script message with the syntax as: 
    window.external.ptc ('ToolkitJSBridge=' + key + '?' + message)
    •  Listener—Listener object.
    UI Command Action Listeners
    Methods introduced:
  • pfcSession::UICreateCommand
    		•
  • pfcUICommandActionListener::OnCommand
    		•
    The pfcSession::UICreateCommand method takes a pfcUICommandActionListener argument and returns a UICommand action source with that action listener already registered. This UICommand object is subsequently passed as an argument to the pfcSession::AddUIButton method that adds a command button to a Creo Parametric menu. The pfcUICommandActionListener::OnCommand method of the registered pfcUICommandActionListener is called whenever the command button is clicked.
    Model Level Action listeners
    Methods introduced:
  • pfcModelActionListener::OnAfterModelSave
    		•
  • pfcModelEventActionListener::OnAfterModelCopy
    		•
  • pfcModelEventActionListener::OnAfterModelRename
    		•
  • pfcModelEventActionListener::OnAfterModelErase
    		•
  • pfcModelEventActionListener::OnAfterModelDelete
    		•
  • pfcModelActionListener::OnAfterModelRetrieve
    		•
  • pfcModelActionListener::OnBeforeModelDisplay
    		•
  • pfcModelActionListener::OnAfterModelCreate
    		•
  • pfcModelActionListener::OnAfterModelSaveAll
    		•
  • pfcModelEventActionListener::OnAfterModelCopyAll
    		•
  • pfcModelActionListener::OnAfterModelEraseAll
    		•
  • pfcModelActionListener::OnAfterModelDeleteAll
    		•
  • pfcModelActionListener::OnAfterModelRetrieveAll
    		•
  • wfcWSession::AddBeforeModelRetrieveListener
    		•
  • wfcBeforeModelRetrieveActionListener::OnBeforeModelRetrieve
    		•
  • wfcBeforeModelRetrieveInstructions::Create
    		•
  • wfcBeforeModelRetrieveInstructions::GetRetrieveOptions
    		•
  • wfcBeforeModelRetrieveInstructions::SetRetrieveOptions
    		•
  • wfcBeforeModelRetrieveInstructions::GetModelFilePath
    		•
  • wfcBeforeModelRetrieveInstructions::SetModelFilePath
    		•
  • wfcBeforeModelSaveAllListener::OnBeforeModelSave
    		•
  • wfcModelParamActionListener::OnBeforeParameterCreate
    		•
  • wfcModelParamActionListener::OnBeforeParameterModify
    		•
  • wfcModelParamActionListener::OnAfterParameterModify
    		•
  • wfcModelParamActionListener::OnAfterParameterDelete
    		•
  • wfcModelAfterRenameAllActionListener::OnAfterModelRenameAll
    		•
  • wfcModelReplaceActionListener::OnAfterModelReplace
    		•
    Methods ending in All are called after any event of the specified type. The call is made even if the user did not explicitly request that the action take place. Methods that do not end in All are only called when the user specifically requests that the event occurs.
    The method pfcModelActionListener::OnAfterModelSave is called after successfully saving a model.
    The method pfcModelEventActionListener::OnAfterModelCopy is called after successfully copying a model.
    The method pfcModelEventActionListener::OnAfterModelRename is called after successfully renaming a model.
    The method pfcModelEventActionListener::OnAfterModelErase is called after successfully erasing a model.
    The method pfcModelEventActionListener::OnAfterModelDelete is called after successfully deleting a model.
    The method pfcModelActionListener::OnAfterModelRetrieve is called after successfully retrieving a model.
    The method pfcModelActionListener::OnBeforeModelDisplay is called before displaying a model.
    The method pfcModelActionListener::OnAfterModelCreate is called after the successful creation of a model.
    The method wfcWSession::AddBeforeModelRetrieveListener supersedes the method wfcWSession::AddModelRetrievePreListener. The method creates a listener. This listener blocks the standard Creo File Open dialog box.
    The method wfcBeforeModelRetrieveActionListener::OnBeforeModelRetrieve supersedes the method wfcBeforeModelRetrieveListener::OnBeforeModelRetrieve. The method wfcBeforeModelRetrieveActionListener::OnBeforeModelRetrieve is called when you activate the File ▶ Open menu. This method contains its own code for handling the File open event. You must replace the standard File Open dialog box with the dialog box created by your application to open files. The method also retrieves the model specified in the object wfcBeforeModelRetrieveInstructions. Use the method wfcBeforeModelRetrieveInstructions::Create to create an instance of wfcBeforeModelRetrieveInstructions object, which specifies the instructions for retrieving the model. The method wfcBeforeModelRetrieveInstructions::SetRetrieveOptions uses the enumerated data type wfcWModelRetrieveOption to specify how the model must be retrieved. Use the method wfcBeforeModelRetrieveInstructions::GetRetrieveOptions to get the type of option used to retrieve the model. The model can be retrieved using the following options:
    •  wfcMODEL_RETRIEVE_NORMAL—Retrieves the models normally.
    •  wfcMODEL_RETRIEVE_SIMP_REP—Retrieves the models as a simplified representation.
    •  wfcMODEL_RETRIEVE_VIEW_ONLY—Used for drawings only. Retrieves the model in view only mode.
    Use the methods wfcBeforeModelRetrieveInstructions::GetModelFilePath and wfcBeforeModelRetrieveInstructions::SetModelFilePath to get and set the file path of the model that must be retrieved. The file path includes the path, file name, extension, and version of the model.
    The method wfcBeforeModelSaveAllListener::OnBeforeModelSave is called before a model has been saved. This method provides more functionality than the existing method pfcSessionActionListener::OnBeforeModelSave. The method wfcBeforeModelSaveAllListener::OnBeforeModelSave is called on the current model and also its dependents. For example, before saving an assembly, the method is called on the assembly and also on all the assembly components. It is also called for various user actions such as, saving a copy of the model, checkin of a model, and so on. During conflict resolution, the method may be called more than once.
    The methods in class wfcModelParamActionListener are triggered whenever these events occur for any parameter in the model.
    The method wfcModelParamActionListener::OnBeforeParameterCreate is called before a parameter is created.
    The method wfcModelParamActionListener::OnBeforeParameterModify is called before the parameter is modified.
    The method wfcModelParamActionListener::OnAfterParameterModify is called after the parameter has been successfully modified.
    The method wfcModelParamActionListener::OnAfterParameterDelete is called after the parameter has been deleted.
    The method wfcModelAfterRenameAllActionListener::OnAfterModelRenameAll is called after all the models described using the pfcModelDescriptor object have been renamed.
    The method wfcModelReplaceActionListener::OnAfterModelReplace is called after successfully replacing a model.
    Solid Level Action Listeners
    Methods introduced:
  • pfcSolidActionListener::OnBeforeRegen
    		•
  • pfcSolidActionListener::OnAfterRegen
    		•
  • pfcSolidActionListener::OnBeforeUnitConvert
    		•
  • pfcSolidActionListener::OnAfterUnitConvert
    		•
  • pfcSolidActionListener::OnBeforeFeatureCreate
    		•
  • pfcSolidActionListener::OnAfterFeatureCreate
    		•
  • pfcSolidActionListener::OnAfterFeatureDelete
    		•
    The pfcSolidActionListener::OnBeforeRegen and pfcSolidActionListener::OnAfterRegen methods occur when the user regenerates a solid object within the pfcActionSource to which the listener is assigned. These methods take the first feature to be regenerated and a handle to the Solid object as arguments. In addition, the method pfcSolidActionListener::OnAfterRegen includes a Boolean argument that indicates whether regeneration was successful.
    Note
    •  It is not recommended to modify geometry or dimensions using the pfcSolidActionListener::OnBeforeRegen method call.
    •  A regeneration that did not take place because nothing was modified is identified as a regeneration failure.
    The pfcSolidActionListener::OnBeforeUnitConvert and pfcSolidActionListener::OnAfterUnitConvert methods activate when a user modifies the unit scheme (by selecting the Creo Parametric command Set Up, Units). The methods receive the Solid object to be converted and a Boolean flag that identifies whether the conversion changed the dimension values to keep the object the same size.
    Note
    SolidActionListeners can be registered with the session object so that its methods are called when these events occur for any solid model that is in session.
    The pfcSolidActionListener::OnBeforeFeatureCreate method activates when the user starts to create a feature that requires the Feature Creation dialog box. Because this event occurs only after the dialog box is displayed, it will not occur at all for datums and other features that do not use this dialog box. This method takes two arguments: the solid model that will contain the feature and the ModelItem identifier.
    The pfcSolidActionListener::OnAfterFeatureCreate method activates after any feature, including datums, has been created. This method takes the new Feature object as an argument.
    The pfcSolidActionListener::OnAfterFeatureDelete method activates after any feature has been deleted. The method receives the solid that contained the feature and the (now defunct) pfcModelItem identifier.
    Feature Level Action Listeners
    Methods introduced:
  • pfcFeatureActionListener::OnBeforeDelete
    		•
  • pfcFeatureActionListener::OnBeforeSuppress
    		•
  • pfcFeatureActionListener::OnAfterSuppress
    		•
  • pfcFeatureActionListener::OnBeforeRegen
    		•
  • pfcFeatureActionListener::OnAfterRegen
    		•
  • pfcFeatureActionListener::OnRegenFailure
    		•
  • pfcFeatureActionListener::OnBeforeRedefine
    		•
  • pfcFeatureActionListener::OnAfterCopy
    		•
  • pfcFeatureActionListener::OnBeforeParameterDelete
    		•
  • wfcFeatureParamActionListener::OnBeforeParameterCreate
    		•
  • wfcFeatureParamActionListener::OnBeforeParameterModify
    		•
  • wfcFeatureParamActionListener::OnAfterParameterModify
    		•
  • wfcFeatureParamActionListener::OnAfterParameterDelete
    		•
    Each method in pfcFeatureActionListener takes as an argument the feature that triggered the event.
    pfcFeatureActionListeners can be registered with the object so that the action listener’s methods are called whenever these events occur for any feature that is in session or with a solid model to react to changes only in that model.
    The method pfcFeatureActionListener::OnBeforeDelete is called before a feature is deleted.
    The method pfcFeatureActionListener::OnBeforeSuppress is called before a feature is suppressed.
    The method pfcFeatureActionListener::OnAfterSuppress is called after a successful feature suppression.
    The method pfcFeatureActionListener::OnBeforeRegen is called before a feature is regenerated.
    The method pfcFeatureActionListener::OnAfterRegen is called after a successful feature regeneration.
    The method pfcFeatureActionListener::OnRegenFailure is called when a feature fails regeneration.
    The method pfcFeatureActionListener::OnBeforeRedefine is called before a feature is redefined.
    The method pfcFeatureActionListener::OnAfterCopy is called after a feature has been successfully copied.
    The method pfcFeatureActionListener::OnBeforeParameterDelete is called before a feature parameter is deleted.
    The methods in wfcFeatureParamActionListener are triggered whenever these events occur for any parameter in the feature.
    The method wfcFeatureParamActionListener::OnBeforeParameterCreate is called before a parameter is created.
    The method wfcFeatureParamActionListener::OnBeforeParameterModify is called before the parameter is modified.
    The method wfcFeatureParamActionListener::OnAfterParameterModify is called after the parameter has been successfully modified.
    The method wfcFeatureParamActionListener::OnAfterParameterDelete is called after the parameter has been deleted.
    Cancelling an ActionListener Operation
    Creo Object TOOLKIT C++ allows you to cancel certain notification events, registered by the action listeners.
    Methods Introduced:
  • pfcXCancelProEAction::Throw
    		•
    The static method pfcXCancelProEAction::Throw must be called from the body of an action listener to cancel the impending Creo Parametric operation. This method will throw a Creo Object TOOLKIT C++ exception signalling to Creo Parametric to cancel the listener event.
    Note: Your application should not catch the Creo Object TOOLKIT C++ exception, or should rethrow it if caught, so that Creo Parametric is forced to handle it.
    The following events can be cancelled using this technique:
    •  pfcSessionActionListener::OnBeforeModelErase
    •  pfcSessionActionListener::OnBeforeModelDelete
    •  pfcSessionActionListener::OnBeforeModelRename
    •  pfcSessionActionListener::OnBeforeModelSave
    •  pfcSessionActionListener::OnBeforeModelPurge
    •  pfcSessionActionListener::OnBeforeModelCopy
    •  pfcModelActionListener::OnBeforeParameterCreate
    •  pfcModelActionListener::OnBeforeParameterDelete
    •  pfcModelActionListener::OnBeforeParameterModify
    •  pfcFeatureActionListener::OnBeforeDelete
    •  pfcFeatureActionListener::OnBeforeSuppress
    •  pfcFeatureActionListener::OnBeforeParameterDelete
    •  pfcFeatureActionListener::OnBeforeParameterCreate
    •  pfcFeatureActionListener::OnBeforeRedefine