Action Listeners
This section describes the VB API methods that enable you to use action listeners.
The VB API Action Listeners
An ActionListener is a class that is assigned to respond to certain events. In the VB API, 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 the VB API 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 VB API 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:
  • IpfcActionSource.AddActionListener
    		•
  • IpfcActionSource.AddActionListenerWithType
    		•
  • IpfcActionSource.RemoveActionListener
    		•
    Many VB API classes inherit the IpfcActionSource interface, but only the following classes currently make calls to the methods of registered IpfcActionListeners:
    •  IpfcSession
    ○  Session Action Listener
    ○  Model Action Listener
    ○  Solid Action Listener
    ○  Model Event Action Listener
    ○  Feature Action Listener
    •  IpfcUICommand
    ○  UI Action Listener
    •  IpfcModel (and it’s subclasses)
    ○  Model Action Listener
    ○  Parameter Action Listener
    •  IpfcSolid (and it’s subclasses)
    ○  Solid Action Listener
    ○  Feature Action Listener
    •  IpfcFeature (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 IpfcActionSource.AddActionListener adds action listeners to notify you of all the events.
    ○  The method IpfcActionSource.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:
  • IpfcSessionActionListener.OnAfterDirectoryChange()
    		•
  • IpfcSessionActionListener.OnAfterWindowChange()
    		•
  • IpfcSessionActionListener.OnAfterModelDisplay()
    		•
  • IpfcSessionActionListener.OnBeforeModelErase()
    		•
  • IpfcSessionActionListener.OnBeforeModelDelete()
    		•
  • IpfcSessionActionListener.OnBeforeModelRename()
    		•
  • IpfcSessionActionListener.OnBeforeModelSave()
    		•
  • IpfcSessionActionListener.OnBeforeModelPurge()
    		•
  • IpfcSessionActionListener.OnBeforeModelCopy()
    		•
  • IpfcSessionActionListener.OnAfterModelPurge()
    		•
    The IpfcSessionActionListener.OnAfterDirectoryChange() method activates after the user changes the working directory. This method takes the new directory path as an argument.
    The IpfcSessionActionListener.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 IpfcSessionActionListener.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 IpfcSessionActionListener.OnBeforeModelErase(), IpfcSessionActionListener.OnBeforeModelRename, IpfcSessionActionListener.OnBeforeModelSave, and IpfcSessionActionListener.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:
  • IpfcSession.UICreateCommand()
    		•
  • IpfcUICommandActionListener.OnCommand()
    		•
    The IpfcSession.UICreateCommand() method takes a IpfcUICommandActionListener argument and returns a IpfcUICommand action source with that action listener already registered. This IpfcUICommand object is subsequently passed as an argument to the IpfcSession.UIAddButton() method that adds a command button to a Creo Parametric menu. The IpfcUICommandActionListener.OnCommand method of the registered IpfcUICommandActionListener is called whenever the command button is clicked.
    Model Level Action listeners
    Methods introduced:
  • IpfcModelActionListener.OnAfterModelSave()
    		•
  • IpfcModelEventActionListener.OnAfterModelCopy()
    		•
  • IpfcModelEventActionListener.OnAfterModelRename()
    		•
  • IpfcModelEventActionListener.OnAfterModelErase()
    		•
  • IpfcModelEventActionListener.OnAfterModelDelete()
    		•
  • IpfcModelActionListener.OnAfterModelRetrieve()
    		•
  • IpfcModelActionListener.OnBeforeModelDisplay()
    		•
  • IpfcModelActionListener.OnAfterModelCreate()
    		•
  • IpfcModelActionListener.OnAfterModelSaveAll()
    		•
  • IpfcModelEventActionListener.OnAfterModelCopyAll()
    		•
  • IpfcModelActionListener.OnAfterModelEraseAll()
    		•
  • IpfcModelActionListener.OnAfterModelDeleteAll()
    		•
  • IpfcModelActionListener.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 IpfcModelActionListener.OnAfterModelSave() is called after successfully saving a model.
    The method IpfcModelEventActionListener.OnAfterModelCopy() is called after successfully copying a model.
    The method IpfcModelEventActionListener.OnAfterModelRename() is called after successfully renaming a model.
    The method IpfcModelEventActionListener.OnAfterModelErase() is called after successfully erasing a model.
    The method IpfcModelEventActionListener.OnAfterModelDelete() is called after successfully deleting a model.
    The method IpfcModelActionListener.OnAfterModelRetrieve() is called after successfully retrieving a model.
    The method IpfcModelActionListener.OnBeforeModelDisplay() is called before displaying a model.
    Note
    The method IpfcModelActionListener.OnBeforeModelDisplay() is not supported in asynchronous mode.
    The method IpfcModelActionListener.OnAfterModelCreate() is called after the successful creation of a model.
    Solid Level Action Listeners
    Methods introduced:
  • IpfcSolidActionListener.OnBeforeRegen()
    		•
  • IpfcSolidActionListener.OnAfterRegen()
    		•
  • IpfcSolidActionListener.OnBeforeUnitConvert()
    		•
  • IpfcSolidActionListener.OnAfterUnitConvert()
    		•
  • IpfcSolidActionListener.OnBeforeFeatureCreate()
    		•
  • IpfcSolidActionListener.OnAfterFeatureCreate()
    		•
  • IpfcSolidActionListener.OnAfterFeatureDelete()
    		•
    The IpfcSolidActionListener.OnBeforeRegen() and IpfcSolidActionListener.OnAfterRegen() methods occur when the user regenerates a solid object within the IpfcActionSource to which the listener is assigned. These methods take the first feature to be regenerated and a handle to the IpfcSolid object as arguments. In addition, the method IpfcSolidActionListener.OnAfterRegenerate() includes a Boolean argument that indicates whether regeneration was successful.
    Note
    •  It is not recommended to modify geometry or dimensions using the IpfcSolidActionListener.OnBeforeRegenerate() method call.
    •  A regeneration that did not take place because nothing was modified is identified as a regeneration failure.
    The methods IpfcSolidActionListener.OnBeforeUnitConvert() and IpfcSolidActionListener.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
    IpfcSolidActionListeners 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 IpfcSolidActionListener.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 IpfcModelItem identifier.
    The IpfcSolidActionListener.OnAfterFeatureCreate() method activates after any feature, including datums, has been created. This method takes the new IpfcFeature object as an argument.
    The IpfcSolidActionListener.OnAfterFeatureDelete() method activates after any feature has been deleted. The method receives the solid that contained the feature and the (now defunct) IpfcModelItem identifier.
    Selection Level Action Listeners
    Method introduced:
  • IpfcSelectionBufferListener.OnAfterSelBufferChange()
    		•
    The method
  • IpfcSelectionBufferListener.OnAfterSelBufferChange()
    •  is called after the selection buffer is changed.
    Feature Level Action Listeners
    Methods introduced:
  • IpfcFeatureActionListener.OnBeforeDelete()
    		•
  • IpfcFeatureActionListener.OnBeforeSuppress()
    		•
  • IpfcFeatureActionListener.OnAfterSuppress()
    		•
  • IpfcFeatureActionListener.OnBeforeRegen()
    		•
  • IpfcFeatureActionListener.OnAfterRegen()
    		•
  • IpfcFeatureActionListener.OnRegenFailure()
    		•
  • IpfcFeatureActionListener.OnBeforeRedefine()
    		•
  • IpfcFeatureActionListener.OnAfterCopy()
    		•
  • IpfcFeatureActionListener.OnBeforeParameterDelete()
    		•
    Each method in IpfcFeatureActionListener takes as an argument the feature that triggered the event.
    IpfcFeatureActionListeners 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 IpfcFeatureActionListener.OnBeforeDelete() is called before a feature is deleted.
    The method IpfcFeatureActionListener.OnBeforeSuppress() is called before a feature is suppressed.
    The method IpfcFeatureActionListener.OnAfterSuppressv is called after a successful feature suppression.
    The method IpfcFeatureActionListener.OnBeforeRegen() is called before a feature is regenerated.
    The method IpfcFeatureActionListener.OnAfterRegenv is called after a successful feature regeneration.
    The method IpfcFeatureActionListener.OnRegenFailure() is called when a feature fails regeneration.
    The method IpfcFeatureActionListener.OnBeforeRedefine() is called before a feature is redefined.
    The method IpfcFeatureActionListener.OnAfterCopy() is called after a feature has been successfully copied.
    The method IpfcFeatureActionListener.OnBeforeParameterDelete() is called before a feature parameter is deleted.
    Cancelling an ActionListener Operation
    The VB API 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 the VB API exception signalling to Creo Parametric to cancel the listener event.
    Note: Your application should not catch the VB API 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:
    •  IpfcSessionActionListener.OnBeforeModelErase()
    •  IpfcSessionActionListener.OnBeforeModelDelete()
    •  IpfcSessionActionListener.OnBeforeModelRename()
    •  IpfcSessionActionListener.OnBeforeModelSave()
    •  IpfcSessionActionListener.OnBeforeModelPurge()
    •  IpfcSessionActionListener.OnBeforeModelCopy()
    •  IpfcModelActionListener.OnBeforeParameterCreate()
    •  IpfcModelActionListener.OnBeforeParameterDelete()
    •  IpfcModelActionListener.OnBeforeParameterModify()
    •  IpfcFeatureActionListener.OnBeforeDelete()
    •  IpfcFeatureActionListener.OnBeforeSuppress()
    •  IpfcFeatureActionListener.OnBeforeParameterDelete()
    •  IpfcFeatureActionListener.OnBeforeParameterCreate()
    •  IpfcFeatureActionListener.OnBeforeRedefine()