Most operations require some input from the user before each execution. These options are called User Options and can be:
- The scope of the operation.
- For operations that modify files, whether or not to keep open documents after being processed (to allow undo).
- Some other kind of input specific to the operation.
The user is asked to specify these options through a dialog window that appears before each execution. This dialog window can have a tab page for the scope, a tab page for other kind of input, or both, as you can see in this image:
There are two elements that your operation may need to provide to support user options:
- An instance of the UserOptions class, or of a class which inherits from it. This instance is passed to several methods that you override of the OperationBase class, so you can retrieve the options that the user wants to apply to that execution of the operation.
- A usercontrol that will be hosted as property page in the user options window.
There are two scenarios to consider:
- If your only user option is the scope of operation:
1) You don't need to create a class that inherits from the UserOptions class, you can use it directly (it is not an abstract class).
2) You override the OnCreateUserOptionsForExecution method of the OperationBase class and inside it you create and return an instance of the UserOptions class passing to its constructor the desired scope. If you use the OperationScopeAction.UseSolutionScope value, no property page with the scope selection will be presented to the user.
3) You don't need to provide a usercontrol for the scope property page: the object model provides one automatically.
- If you need to provide other user options apart from the scope:
1) You need to derive a class from the UserOptions class. In the derived class, you add properties for other user options, with the exception of the ModifiedDocumentAction property which is already provided by the UserOptions class. In the constructor of this derived class, you can call the constructor of the base class with the desired scope.
2) You override the OnCreateUserOptionsForExecution method of the OperationBase class and inside it you create and return an instance of the class derived from the UserOptions class.
3) You need to create a usercontrol which is the user interface for the user options.
4) This usercontrol must implement the IUserOptionsPropertyPage interface.
5) The class that derives from the UserOptions class must override the OnCreatePropertyPage method to return an instance of the mentioned usercontrol and the OnGetFriendlyName method to return the caption of the property page.
The external operations supplied as examples show both scenarios.