Action Listeners
This section describes the Creo.JS methods that enable you to use action listeners.
The Creo.JS Action Listeners
An ActionListener is a class that is assigned to respond to certain events. In Creo.JS, 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.JS are defined by these classes:
•  Interface—Named <Object>ActionListener. This interface defines the methods that can respond to various events.
•  Default class—Named Default<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.
Note
When notifications are set in Creo.JS 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.
Action Sources
Methods introduced:
  • pfcActionSource.AddActionListener
    		•
  • pfcActionSource.AddActionListenerWithType
    		•
  • pfcActionSource.RemoveActionListener
    		•
    Many Creo.JS classes inherit the pfcActionSource interface, but only the following classes currently make calls to the methods of registered pfcActionListeners:
    •  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.
    ○  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.
    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()
    		•
    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.
    UI Command Action Listeners
    Methods introduced:
  • pfcSession.UICreateCommand()
    		•
  • pfcUICommandActionListener.OnCommand()
    		•
    The pfcSession.UICreateCommand() method takes a pfcUICommandActionListener argument and returns a pfcUICommand action source with that action listener already registered. This pfcUICommand object is subsequently passed as an argument to the pfcSession.UIAddButton() 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()
    		•
    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.
    Note
    The method pfcModelActionListener.OnBeforeModelDisplay() is not supported in asynchronous mode.
    The method pfcModelActionListener.OnAfterModelCreate() is called after the successful creation of 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 pfcSolid object as arguments. In addition, the method pfcSolidActionListener.OnAfterRegenerate() includes a Boolean argument that indicates whether regeneration was successful.
    Note
    •  It is not recommended to modify geometry or dimensions using the pfcSolidActionListener.OnBeforeRegenerate() method call.
    •  A regeneration that did not take place because nothing was modified is identified as a regeneration failure.
    The methods pfcSolidActionListener.OnBeforeUnitConvert() and pfcSolidActionListener.OnAfterUnitConvert() 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
    pfcSolidActionListeners 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 pfcModelItem identifier.
    The pfcSolidActionListener.OnAfterFeatureCreate() method activates after any feature, including datums, has been created. This method takes the new pfcFeature 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.
    Selection Level Action Listeners
    Method introduced:
  • pfcSelectionBufferListener.OnAfterSelBufferChange
    		•
    The method
  • pfcSelectionBufferListener.OnAfterSelBufferChange
    •  is called after the selection buffer is changed.
    Feature Level Action Listeners
    Methods introduced:
  • pfcFeatureActionListener.OnBeforeDelete()
    		•
  • pfcFeatureActionListener.OnBeforeSuppress()
    		•
  • pfcFeatureActionListener.OnAfterSuppress()
    		•
  • pfcFeatureActionListener.OnBeforeRegen()
    		•
  • pfcFeatureActionListener.OnAfterRegen()
    		•
  • pfcFeatureActionListener.OnRegenFailure()
    		•
  • pfcFeatureActionListener.OnBeforeRedefine()
    		•
  • pfcFeatureActionListener.OnAfterCopy()
    		•
  • pfcFeatureActionListener.OnBeforeParameterDelete()
    		•
    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.OnAfterSuppressv is called after a successful feature suppression.
    The method pfcFeatureActionListener.OnBeforeRegen() is called before a feature is regenerated.
    The method pfcFeatureActionListener.OnAfterRegenv 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.
    Cancelling an ActionListener Operation
    Creo.JS allows you to cancel certain notification events, registered by the action listeners.
    Methods Introduced:
  • CCpfcXCancelProEAction.Throw()
    		•
    The static method CCpfcXCancelProEAction.Throw() must be called from the body of an action listener to cancel the impending Creo Parametric operation. This method will throw a Creo.JS exception signalling to Creo Parametric to cancel the listener event.
    Note: Your application should not catch the Creo.JS 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()