Action Listeners
This section describes the Creo Object TOOLKIT Java methods that enable you to use action listeners.
Creo Object TOOLKIT Java Action Listeners
An ActionListener in Java is a class that is assigned to respond to certain events. In Creo Object TOOLKIT Java, 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 Java 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 Object TOOLKIT Java applications, every time an event is triggered, notification messages are added to the trail files. From Creo Parametric2.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 java file.
Example:
    public class MyApp {
        session.AddActionListener (new SolidAL1());
    }
    
    class SolidAL1 extends DefaultSolidActionListener {
        // Include overridden methods here
    }
To use your action listener in different Java applications, define it in a separate file.
Example:
    MyApp.java:
    import solidAL1;
    
    public class MyApp {
        session.AddActionListener (new SolidAL1());
    }
    
    SolidAL1.java:
    public class SolidAL1 extends DefaultSolidActionListener {
        // Include overridden methods here.
    }
Action Sources
Methods introduced:
  • pfcBase.ActionSource.AddActionListener
    		•
  • pfcBase.ActionSource.AddActionListenerWithType
    		•
  • pfcBase.ActionSource.RemoveActionListener
    		•
    Many Creo Object TOOLKIT Java classes inherit the ActionSource interface, but only the following classes currently make calls to the methods of registered ActionListeners:
    •  pfcSession.Session
    ○  Session Action Listener
    ○  Model Action Listener
    ○  Solid Action Listener
    ○  Model Event Action Listener
    ○  Feature Action Listener
    •  pfcCommand.UICommand
    ○  UI Action Listener
    •  pfcModel.Model (and it’s subclasses)
    ○  Model Action Listener
    ○  Parameter Action Listener
    •  pfcSolid.Solid (and it’s subclasses)
    ○  Solid Action Listener
    ○  Feature Action Listener
    •  pfcFeature.Feature (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 pfcBase.ActionSource.AddActionListener adds action listeners to notify you of all the events.
    ○  The method pfcBase.ActionSource.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:
  • wfcDimension.DimensionActionListener.OnBeforeDimensionValueModify
    		•
    The method wfcDimension.DimensionActionListener.OnBeforeDimensionValueModify is called before the dimension value is modified.
    Session Level Action Listeners
    Methods introduced:
  • pfcSession.SessionActionListener.OnAfterDirectoryChange
    		•
  • pfcSession.SessionActionListener.OnAfterWindowChange
    		•
  • pfcSession.SessionActionListener.OnAfterModelDisplay
    		•
  • pfcSession.SessionActionListener.OnBeforeModelErase
    		•
  • pfcSession.SessionActionListener.OnBeforeModelDelete
    		•
  • pfcSession.SessionActionListener.OnBeforeModelRename
    		•
  • pfcSession.SessionActionListener.OnBeforeModelSave
    		•
  • pfcSession.SessionActionListener.OnBeforeModelPurge
    		•
  • pfcSession.SessionActionListener.OnBeforeModelCopy
    		•
  • pfcSession.SessionActionListener.OnAfterModelPurge
    		•
  • wfcSession.WSession.AddBrowserMessageListener
    		•
    The pfcSession.SessionActionListener.OnAfterDirectoryChange method activates after the user changes the working directory. This method takes the new directory path as an argument.
    The pfcSession.SessionActionListener.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 pfcSession.SessionActionListener.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 pfcSession.SessionActionListener.OnBeforeModelErase, pfcSession.SessionActionListener.OnBeforeModelRename, pfcSession.SessionActionListener.OnBeforeModelSave, and pfcSession.SessionActionListener.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 wfcSession.WSession.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.Session.UICreateCommand
    		•
  • pfcCommand.UICommandActionListener.OnCommand
    		•
    The pfcSession.Session.UICreateCommand method takes a UICommandActionListener argument and returns a UICommand action source with that action listener already registered. This UICommand object is subsequently passed as an argument to the Session.AddUIButton method that adds a command button to a Creo Parametric menu. The pfcCommand.UICommandActionListener.OnCommand method of the registered UICommandActionListener is called whenever the command button is clicked.
    Model Level Action listeners
    Methods introduced:
  • pfcModel.ModelActionListener.OnAfterModelSave
    		•
  • pfcModel.ModelEventActionListener.OnAfterModelCopy
    		•
  • pfcModel.ModelEventActionListener.OnAfterModelRename
    		•
  • pfcModel.ModelEventActionListener.OnAfterModelErase
    		•
  • pfcModel.ModelEventActionListener.OnAfterModelDelete
    		•
  • pfcModel.ModelActionListener.OnAfterModelRetrieve
    		•
  • pfcModel.ModelActionListener.OnBeforeModelDisplay
    		•
  • pfcModel.ModelActionListener.OnAfterModelCreate
    		•
  • pfcModel.ModelActionListener.OnAfterModelSaveAll
    		•
  • pfcModel.ModelEventActionListener.OnAfterModelCopyAll
    		•
  • pfcModel.ModelActionListener.OnAfterModelEraseAll
    		•
  • pfcModel.ModelActionListener.OnAfterModelDeleteAll
    		•
  • wfcSession.WSession.AddBeforeModelRetrieveListener
    		•
  • wfcSession.BeforeModelRetrieveActionListener.OnBeforeModelRetrieve
    		•
  • wfcSession.wfcSession.BeforeModelRetrieveInstructions_Create
    		•
  • wfcSession.BeforeModelRetrieveInstructions.GetRetrieveOptions
    		•
  • wfcSession.BeforeModelRetrieveInstructions.SetRetrieveOptions
    		•
  • wfcSession.BeforeModelRetrieveInstructions.GetModelFilePath
    		•
  • wfcSession.BeforeModelRetrieveInstructions.SetModelFilePath
    		•
  • wfcSession.BeforeModelSaveAllListener.OnBeforeModelSave
    		•
  • wfcSession.BeforeModelRetrieveListener.OnBeforeModelRetrieve
    		•
  • wfcModel.ModelParamActionListener.OnBeforeParameterCreate
    		•
  • wfcModel.ModelParamActionListener.OnBeforeParameterModify
    		•
  • wfcModel.ModelParamActionListener.OnAfterParameterModify
    		•
  • wfcModel.ModelParamActionListener.OnAfterParameterDelete
    		•
  • wfcModel.ModelAfterRenameAllActionListener.OnAfterModelRenameAll
    		•
  • wfcModel.ModelReplaceActionListener.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 pfcModel.ModelActionListener.OnAfterModelSave is called after successfully saving a model.
    The method pfcModel.ModelEventActionListener.OnAfterModelCopy is called after successfully copying a model.
    The method pfcModel.ModelEventActionListener.OnAfterModelRename is called after successfully renaming a model.
    The method pfcModel.ModelEventActionListener.OnAfterModelErase is called after successfully erasing a model.
    The method pfcModel.ModelEventActionListener.OnAfterModelDelete is called after successfully deleting a model.
    The method pfcModel.ModelActionListener.OnAfterModelRetrieve is called after successfully retrieving a model.
    The method pfcModel.ModelActionListener.OnBeforeModelDisplay is called before displaying a model.
    Note
    The method pfcModel.ModelActionListener.OnBeforeModelDisplay is not supported in asynchronous mode.
    The method pfcModel.ModelActionListener.OnAfterModelCreate is called after the successful creation of a model.
    The method wfcSession.WSession.AddBeforeModelRetrieveListener supersedes the method wfcSession.WSession.AddModelRetrievePreListener. The method creates a listener. This listener blocks the standard Creo File Open dialog box.
    The method wfcSession.WSession.AddModelRetrievePreListener creates a listener. This listener blocks the standard Creo File Open dialog box.
    The method wfcSession.BeforeModelRetrieveActionListener.OnBeforeModelRetrieve supersedes the method wfcSession.BeforeModelRetrieveListener.OnBeforeModelRetrieve. The method wfcSession.BeforeModelRetrieveActionListener.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 wfcSession.BeforeModelRetrieveInstructions. Use the method wfcSession.wfcSession.BeforeModelRetrieveInstructions_Create to create an instance of wfcSession.BeforeModelRetrieveInstructions object, which specifies the instructions for retrieving the model. The method wfcSession.BeforeModelRetrieveInstructions.SetRetrieveOptions uses the enumerated data type wfcSession.WModelRetrieveOption to specify how the model must be retrieved. Use the method wfcSession.BeforeModelRetrieveInstructions.GetRetrieveOptions to get the type of option used to retrieve the model. The model can be retrieved using the following options:
    •  MODEL_RETRIEVE_NORMAL—Retrieves the models normally.
    •  MODEL_RETRIEVE_SIMP_REP—Retrieves the models as a simplified representation.
    •  MODEL_RETRIEVE_VIEW_ONLY—Used for drawings only. Retrieves the model in view only mode.
    Use the methods wfcSession.BeforeModelRetrieveInstructions.GetModelFilePath and wfcSession.BeforeModelRetrieveInstructions.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 wfcSession.BeforeModelSaveAllListener.OnBeforeModelSave is called before a model has been saved. This method provides more functionality than the existing method pfcSession.SessionActionListener.OnBeforeModelSave. The method wfcSession.BeforeModelSaveAllListener.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 interface com.ptc.wfc.wfcModelParamActionListener are triggered whenever these events occur for any parameter in the model.
    The method wfcModel.ModelParamActionListener.OnBeforeParameterCreate is called before a parameter is created.
    The method wfcModel.ModelParamActionListener.OnBeforeParameterModify is called before the parameter is modified.
    The method wfcModel.ModelParamActionListener.OnAfterParameterModify is called after the parameter has been successfully modified.
    The method wfcModel.ModelParamActionListener.OnAfterParameterDelete is called after the parameter has been deleted.
    The method wfcModel.ModelAfterRenameAllActionListener.OnAfterModelRenameAll is called after all the models described using the pfcModel.ModelDescriptor object have been renamed.
    The method wfcModel.ModelReplaceActionListener.OnAfterModelReplace is called after successfully replacing a model.
    Solid Level Action Listeners
    Methods introduced:
  • pfcSolid.SolidActionListener.OnBeforeRegen
    		•
  • pfcSolid.SolidActionListener.OnAfterRegen
    		•
  • pfcSolid.SolidActionListener.OnBeforeUnitConvert
    		•
  • pfcSolid.SolidActionListener.OnAfterUnitConvert
    		•
  • pfcSolid.SolidActionListener.OnBeforeFeatureCreate
    		•
  • pfcSolid.SolidActionListener.OnAfterFeatureCreate
    		•
  • pfcSolid.SolidActionListener.OnAfterFeatureDelete
    		•
    The pfcSolid.SolidActionListener.OnBeforeRegen and pfcSolid.SolidActionListener.OnAfterRegen methods occur when the user regenerates a solid object within the ActionSource 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 pfcSolid.SolidActionListener.OnAfterRegenerate includes a Boolean argument that indicates whether regeneration was successful.
    Note
    •  It is not recommended to modify geometry or dimensions using the pfcSolid.SolidActionListener.OnBeforeRegenerate method call.
    •  A regeneration that did not take place because nothing was modified is identified as a regeneration failure.
    The pfcSolid.SolidActionListener.OnBeforeUnitConvert and pfcSolid.SolidActionListener.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 pfcSolid.SolidActionListener.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 pfcSolid.SolidActionListener.OnAfterFeatureCreate method activates after any feature, including datums, has been created. This method takes the new Feature object as an argument.
    The pfcSolid.SolidActionListener.OnAfterFeatureDelete method activates after any feature has been deleted. The method receives the solid that contained the feature and the (now defunct) ModelItem identifier.
    Selection Level Action Listeners
    Method introduced:
  • pfcSelection.SelectionBufferListener.OnAfterSelBufferChange
    		•
    The method
  • pfcSelection.SelectionBufferListener.OnAfterSelBufferChange
    •  is called after the selection buffer is changed.
    Feature Level Action Listeners
    Methods introduced:
  • pfcFeature.FeatureActionListener.OnBeforeDelete
    		•
  • pfcFeature.FeatureActionListener.OnBeforeSuppress
    		•
  • pfcFeature.FeatureActionListener.OnAfterSuppress
    		•
  • pfcFeature.FeatureActionListener.OnBeforeRegen
    		•
  • pfcFeature.FeatureActionListener.OnAfterRegen
    		•
  • pfcFeature.FeatureActionListener.OnRegenFailure
    		•
  • pfcFeature.FeatureActionListener.OnBeforeRedefine
    		•
  • pfcFeature.FeatureActionListener.OnAfterCopy
    		•
  • pfcFeature.FeatureActionListener.OnBeforeParameterDelete
    		•
  • wfcFeature.FeatureParamActionListener.OnBeforeParameterCreate
    		•
  • wfcFeature.FeatureParamActionListener.OnBeforeParameterModify
    		•
  • wfcFeature.FeatureParamActionListener.OnAfterParameterModify
    		•
  • wfcFeature.FeatureParamActionListener.OnAfterParameterDelete
    		•
    Each method in FeatureActionListener takes as an argument the feature that triggered the event.
    FeatureActionListeners 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 pfcFeature.FeatureActionListener.OnBeforeDelete is called before a feature is deleted.
    The method pfcFeature.FeatureActionListener.OnBeforeSuppress is called before a feature is suppressed.
    The method pfcFeature.FeatureActionListener.OnAfterSuppress is called after a successful feature suppression.
    The method pfcFeature.FeatureActionListener.OnBeforeRegen is called before a feature is regenerated.
    The method pfcFeature.FeatureActionListener.OnAfterRegen is called after a successful feature regeneration.
    The method pfcFeature.FeatureActionListener.OnRegenFailure is called when a feature fails regeneration.
    The method pfcFeature.FeatureActionListener.OnBeforeRedefine is called before a feature is redefined.
    The method pfcFeature.FeatureActionListener.OnAfterCopy is called after a feature has been successfully copied.
    The method pfcFeature.FeatureActionListener.OnBeforeParameterDelete is called before a feature parameter is deleted.
    The methods in com.pfc.wfc.wfcFeatureParamActionListener are triggered whenever these events occur for any parameter in the feature.
    The method wfcFeature.FeatureParamActionListener.OnBeforeParameterCreate is called before a parameter is created.
    The method wfcFeature.FeatureParamActionListener.OnBeforeParameterModify is called before the parameter is modified.
    The method wfcFeature.FeatureParamActionListener.OnAfterParameterModify is called after the parameter has been successfully modified.
    The method wfcFeature.FeatureParamActionListener.OnAfterParameterDelete is called after the parameter has been deleted.
    Cancelling an ActionListener Operation
    Creo Object TOOLKIT Java allows you to cancel certain notification events, registered by the action listeners.
    Methods Introduced:
  • pfcExceptions.XCancelProEAction.Throw
    		•
    The static method pfcExceptions.XCancelProEAction.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 Java exception signalling to Creo Parametric to cancel the listener event.
    Note: Your application should not catch the Creo Object TOOLKIT Java 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:
    •  pfcSession.SessionActionListener.OnBeforeModelErase
    •  pfcSession.SessionActionListener.OnBeforeModelDelete
    •  pfcSession.SessionActionListener.OnBeforeModelRename
    •  pfcSession.SessionActionListener.OnBeforeModelSave
    •  pfcSession.SessionActionListener.OnBeforeModelPurge
    •  pfcSession.SessionActionListener.OnBeforeModelCopy
    •  pfcModel.ModelActionListener.OnBeforeParameterCreate
    •  pfcModel.ModelActionListener.OnBeforeParameterDelete
    •  pfcModel.ModelActionListener.OnBeforeParameterModify
    •  pfcFeature.FeatureActionListener.OnBeforeDelete
    •  pfcFeature.FeatureActionListener.OnBeforeSuppress
    •  pfcFeature.FeatureActionListener.OnBeforeParameterDelete
    •  pfcFeature.FeatureActionListener.OnBeforeParameterCreate
    •  pfcFeature.FeatureActionListener.OnBeforeRedefine