An options page allows a plug-in developer to add controls to the ReSharper Options dialog. This is typically used to let the user specify various plug-in settings. The plug-in writer can add an unlimited amount of option pages to the dialog, and the dialogs can be nested in any of the options groups.
Here is a screenshot of a custom options page in action:
Let us now discuss the way in which option pages are defined.
Making an options page
Making an options page is surprisingly easy. You begin by defining a class which will house the options page. This class should be made to inherit
AOptionsPage, and should be decorated with the
OptionsPage attribute requires the plug-in author to provide the following parameters:
- The page ID. This ID can be specified as a constant field inside the class. The page ID is a string which uniquely identifies this particular options page.
- The name of the page. This is the text that will appear in the left-hand tree on the Options page as well as in the title and navigation elements.
- The image name. This refers to the glyph that appears next to the item in the tree. The image can be specified without extension. The image is, by itself, an embedded resource. If you don't want to specify the resource name fully, use the assembly-level
ImagesBaseattribute to define the location where you plan to keep all the images.
In addition, you may specify the following optional parameters:
ParentIdlets you define the ID of the section or element which serves as this page's parent. If you want the parent to be one of the known ReSharper items, look inside the
JetBrains.UI.Options.OptionsPagesnamespace for the corresponding pages, and then use their
Pidas this parameter. For example, for an options page to appear in the Environment section, you specify the
Sequencelets you define the location of the item you are inserting in relation to the other items. Items are placed in order, so the higher this value, the further this page will be in the list of items. Of course, to accurately position the item, you need to know the
Sequencevalue of its siblings. Luckily, this information is available in the metadata.
Having specified the attributes, your class will appear as follows:
In addition to decorating the class, you also need to call its base constructor. As a result, your constructor will need to take at least the following two parameters:
Lifetime, which controls the lifetime of this page.
SettingsStore, the settings store.
These two values, which will be injected by the ReSharper infrastructure, need to be passed to the base class, together with this page's
In addition to these values, you may inject any other available component into the service.
Defining the UI
You can define the UI for your options page using either Windows Forms or WPF. Whichever option you choose, all you have to do to actually present the UI is to initialize it and assign it to your option page's
Note: whichever UI framework you choose, your application must reference the WPF assemblies. The compiler will warn you about this if you start using the
EitherControl type without adding appropriate references.
To create an options page using Windows Forms, simply create a
UserControl and assign it to the
Control property. Please note that since multiple inheritance is impossible, the only way to keep the options page class and the
UserControl class one and the same is as follows:
- Instead of inheriting from
AOptionsPage, inherit from
UserControland implement the
- Decorate the control with the
OptionsPageattribute as described above.
- Use the constructor that you want - there is no need to inject, e.g.,
Lifetimeif you don't need it. (There is no base class that this information must be passed to.
- Implement the read-only property
Control, returning the value of
To create an options page using WPF, simply define your UI in terms of WPF elements and then assign the
Control property accordingly. You can specify any WPF control, e.g.,
Grid, as the page control.
Needless to say, it is entirely possible to use the
WindowsFormsHost class to host Windows Forms controls on a WPF options page. The mechanism which binds the controls to the settings works for both WPF and Windows Forms. (Of course, if you implement
IOptionsPage manually, you can simply assign properties manually without using bindings at all.)
Working with Settings
AOptionsPage from which we inherit has a number of helper
Bind method that help us bind various control properties to our settings. These bind methods have two generic arguments - the name of the settings class, and the type of property that is being saved. In the case of WPF, you would specify:
- The property that is being assigned on exit. Defined as a lambda expression (e.g.,
x => x.Name).
- The name of the control that the property is being read from.
- The dependency property that is being read.
For example, here is how one would bind a WPF text box for a username to a corresponding setting:
The situation with WinForms is a bit more trickly - there are no dependency properties to be used, so we use the
WinFormsProperty helper class. This helper class has a single method,
Create(), that creates an object of type
T is the property type). To create the property, it requires the following parameters:
Lifetimeof the calling component. This should be obvious, since the 'proxy property' should only live as long as it is needed. This does, of course, imply that you must inject the
Lifetimeinto the constructor.
- The class to take data from. In actual fact, though in the case of WinForms you'll probably provide the corresponding control, this doesn't have to be a control per se - it can be practically any object. After all, the
WinFormsPropertyclass does not use any WinForms-specific code.
- A lambda expression indicating which property of the aforementioned class that is to be used.
Thus, the call to bind a WinForms-based password box to a setting becomes as follows: