OptionsForm and OptionsPanel, two classes to easily manage application options

• Download demo executable - 34.2 Kb
• Download demo project - 53.1 Kb
• Download sources - 25.5 Kb

Introduction

.NET offers a powerful tool to manage program options, and that is the data-binding and settings classes, which can serialize and store any type of data. This is great, but it would be better if these tools worked as they should. In fact, when you bind data (and specifically settings in this case) with your control, there are always some problems on handling the binding. These problems often are caused by the designer, which doesn't allow you to access some option in binding (for example, the *direction* of the binding). The only solution is editing the code, for each control you bind a setting to...but that's annoying to do in each application that uses some type of settings. For this reason, I thought to do a resuable set of controls to make my life easier with settings (and bindings in general).

Using the code

As always, I wrote my code to be the as usable as I could. To be extremely clear, I'll show a step-by-step how-to-do:

1. Include the source files in your project or add a reference to OptionsLib.dll.
   
2. Right click on your project and select Add -> New Item; in the dialog that pops up, select Inherited Form, put a name. and select OK. In the next screen, select as the base form OptionsForm, and the form is added. Go to the default constructor of the form and set a : base (Settings) inheritance for the default constructor, where settings is an instance of a SettingBase derived class (for instance, Properties.Settings.Default, the default Settings object generated by Visual Studio). Then you could set some options.
3. Right click again on your project and select Add -> New Item; in the dialog that pops up, select Inherited UserControl, put a name (for instance SomethingPanel) and select OK. In the next screen, select as the base class OptionsPanel, and the UserControl is added.
   
4. Go to the just added OptionsPanel control (for instance SomethingPanel) properties, and scroll down to the Options Form category. The CategoryPath property indicates the TreeView path at which the OptionsPanel is placed. You can use this syntax "Options\Path{"Display Text of the TreeNode"}\SomethingPanel" without the external quotes; each subpath (Options,Path) defines a TreeNode parent name (which doesn't correspond to an OptionsPanel); instead the text between {" and "} is the label of the TreeNode, that is, the text which appears in the TreeView list (if you don't specify a label, the name will be used). The label for the SomethingPanel is contained in the DisplayName property of the panel itself, and if you leave it blank, the panel label will remain blank. In addition, you can specify the AccessibleDescription property and it will appear in the little category description box at the bottom-left of the OptionsForm.
   
5. Now return back to the OptionsForm inherited form (added at point 2) the constructor, and inside of it call

   Panels.Add(new SomethingPanel());
   

6. Now, you can add all controls you like to your SomethingPanel through the designer, setting application bindings (or data ones, even if I didn't try this last, it should work) to the properties of the controls. In addition, you can set the AccessibleDescription property of the controls added into the panel, and the AccessibleDescription text will appear on the description box in the OptionsForm when the user enters the control with the mouse. You don't have to mind for the bindings because the control will do, and it will automatically disable/enable the Apply button. If the settings change, it will automatically save/cancel the changed settings if the user clicks Apply or OK or Cancel.

OptionsForm Properties

[Category("Options Form")]
[Description("Images used in the category tree")]
public ImageList CategoryImages

[Category("Options Form")]
[Description("Indicates the width of the Category Tree Box")]
public int CategoryTreeWidth

[Category("Options Form")]
[Description("This is the Text for the category header box")]
public String CategoryHeaderText

[Category("Options Form")]
[Description("This is the Text for the OK button")]
public String OkButtonText

[Category("Options Form")]
[Description("This is the Text for the Apply button")]

[Category("Options Form")]
[Description("This is the Text for the Cancel button")]
public String CancelButtonText

[Category("Options Form")]
[Description("This is the Text for the 
    Application Must Restart label box")]
public String AppRestartText

[Category("Options Form Colors")]
[Description("Indicates the background color for each box")]
public Color BoxBackColor

[Category("Options Form Colors")]
[Description("Indicates the foreground color 
    for the options panel path box")]
public Color OptionsPathForeColor

[Category("Options Form Colors")]
[Description("Indicates the foreground color for 
       the Application Must Restart label box")]
public Color AppRestartForeColor

[Category("Options Form Descriptions")]
[Description("This is the default Text for the description 
       box when no description is available")]
public String OptionsNoDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the 
       Category Header box when the mouse hover it")]
public String CategoryHeaderDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the Options 
       Panel Path box when the mouse hover it")]
public String OptionsPanelPathDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the Category 
              Tree box when the mouse hover it")]
public String CategoryTreeDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the Category 
              Description box when the mouse hover it")]
public String CategoryDescrDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the Option 
              Description box when the mouse hover it")]
public String OptionDescrDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the Application 
              Must Restart box when the mouse hover it")]
public String ApplicationRestartDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the 
              OK Form Button when the mouse hover it")]
public String OkButtonDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the 
              Apply Form Button when the mouse hover it")]
public String ApplyButtonDescription

[Category("Options Form Descriptions")]
[Description("This is the description for the Cancel 
              Form Button when the mouse hover it")]
public String CancelButtonDescription

[Category("Options Form Flags")]
[Description("Indicates if the Application Must Restart box must appear")]
public bool ApplicationMustRestart

[Category("Options Form Flags")]
[Description("Indicates if the Category Header box must be visible")]
public bool ShowCategoryHeader

[Category("Options Form Flags")]
[Description("Indicates if the Category Description box must be visible")]
public bool ShowCategoryDescription

[Category("Options Form Flags")]
[Description("Indicates if the Options Description box must be visible")]
public bool ShowOptionsDescription

[Category("Options Form Flags")]
[Description("Indicates if first Panel must be selected 
              when selection is on a parent Category.")]
public bool SelectFirstPanel

[Category("Options Form Flags")]
[Description("Indicates if the Options Panel Path box must be visible")]
public bool ShowOptionsPanelPath

[Category("Options Form Flags")]
[Description("Indicates if the Splitter capacity 
              is enabled for the Options Form")]
public bool EnableFormSplitter

[Category("Options Form Flags")]
[Description("Indicates if the Options form will 
              automatically save the Application Settings")]
public bool AutomaticSaveSettings

[Category("Options Form Flags")]
[Description("Indicates if the Apply button must be 
              always enabled (and not only when an option change)")]
public bool ApplyAlwaysEnabled

[Category("Options Form Flags")]
[Description("Indicates if the Apply button must be always 
              enabled (and not only when an option change)")]
public bool SaveAndCloseOnReturn

OptionsForm Events

[Category("Action")]
[Description("This event occurs when the form options 
      must be saved (click on Apply or OK form buttons)")]
public event EventHandler OptionsSaving;

[Category("Action")]
[Description("This event occurs when the form options have been saved")]
public event EventHandler OptionsSaved;

[Category("Action")]
[Description("This event occurs when the form items 
        must be reset (click on Cancel form button)")]
public event EventHandler ResetForm;

These events are automatically handled in OptionsPanels so you don't need to add event handlers for those events, only override the respective methods.

Conclusion

So, that's all, I think. I hope you'll find it useful, bye!