Setup / Settings

Overview

This page provides a description of the new 2.0 Settings API (CFSetup Class Usage).

Refer to the SDK examples HelloWorld and SimpleList projects for basic working examples (Setup.cs, Setup.vb, Seup.cpp).

Advanced and Basic Settings

Centrafuse Settings have 2 states, basic mode, and advanced mode. A plugin may have all settings basic, all advanced, or some settings advanced only. Common settings to make advanced are ones that usually are set once, and then never touched again. The CF_showAdvancedSettings flag can be checked when needed to see whether the user is in Advanced or Basic mode. Examples of new settings API usage can be found in the example source codes included in this SDK, in the Setup.cs, Setup.vb, and Setup.cpp files.

The Setup constructor

Your plugin dll will contain a setup class that inherits from CFSetup, and it will contain a constructor where a variey of Setup flags can, or must, be set. The constructor should also load language files and config files for use while the setup dialog is open. See The CFPlugin Interface Functions example code (in the CF_pluginShowSetup() function) to see how the settings dialog is instantiated and used by the caller.

 public Setup()
 {
     // Set the number of pages this setup has in basic mode
     totalpages = 1;
 
     // If user has advanced settings turned on, then the CF_showAdvancedSettings flag will be set to true
     // Some plugins may require more pages for advanced settings, this must be determined by plugin developer.
     if (CF_showAdvancedSettings)
         totalpages = 1;
 
     // Current page when settings are opened is always 1
     currentpage = 1;
 
     // Builds the controls.
     buildControls();
 
     // Loads the plugin configuration from the specified path.
     this.CF_loadConfig(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData) + "\\Centrafuse\\" + PluginPath + ConfigurationFile);
 
     // Loads the plugin language file from the specified path. This is loaded using the language 
     // specified in the configuration file.
     this.CF_loadLang(PluginPathLanguages + this.pluginConfig.readPluginField("/APPCONFIG/APPLANG") + ".xml");
 
     // Loads the configuration file into the local XmlDocument.
     configxml.Load(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData) + "\\Centrafuse\\" + PluginPath + ConfigurationFile);
     languagexml.Load(PluginPathLanguages + this.pluginConfig.readPluginField("/APPCONFIG/APPLANG") + ".xml");
 }

The setupSection() Function

A Plugin setup shall contain a function to build the setup page, once it is instantiated, and once the MainForm property has been set in the code that is instantiating this class. The setupSection() function shall call buildSetup() and loadSetupPage(), which are internal public CFSetup functions, and update any setup page general texts, i.e. the OK and Save buttons, and title text. See The CFPlugin Interface Functions example code (in the CF_pluginShowSetup() function) to see how this function is utilized by the caller.

 public void setupSection()
 {
     // Build controls
     this.buildSetup();
 
     // Populate the setup page
     this.loadSetupPage();
 
     // Populate button texts
     this.CF_updateButtonText("OK", LanguageReader.getText("APPLANG/BUTTONS/SAVE"));
     this.CF_updateButtonText("CANCEL", LanguageReader.getText("APPLANG/BUTTONS/CANCEL"));
     this.CF_updateText("TITLE", this.pluginLang.readPluginField("/APPLANG/SETUP/TITLE"));
 }

The readConfig() Override

The readConfig() override is the central processing function for a plugin's settings fields and values. The readConfig() functions shall be aware of the current page number, and whether or not Advanced settings are enabled, and with this info the correct data should be displayed for the respective settings page.
It utilizes 3 arrays, one for the button labels/text (ButtonText[]), one for the button value (ButtonValue[]) and one for the button handler (ButtonHandler[]). Each array holds 8 objects of it's respective type corresponding to the 8 settings fields on a setup page, where the ButtonText[] and ButtonValue[] arrays each contain strings, the ButtonHandler[] array contains function delegates that handle the settings button click events. The arrays are applied in sequence to the settings buttons, with array indexes 0-3 represent the left hand side text fields, and indexes 4-7 represent the right side boolean buttons/fields. The SetupButton enumeration can be used to index the array. The readConfig() override should check the variable currentpage if multiple pages of settings are used. In addition, it should check the CF_showAdvancedSettings flag if additional settings are to be shown when in advanced settings mode.

 public override void readConfig()
 {
     try
     {
         int i = SetupButton.One;
 
         if (CF_showAdvancedSettings)
         {
             /*******************************************************************************************/
             /*****  ADVANCED SETTINGS - PAGE 1  ********************************************************/
             /*******************************************************************************************/
             if (currentpage == 1)
             {
 
                 // TEXT BUTTONS (1-4)
 
                 ButtonHandler[i] = new SettingsClickHandler(SetDisplayName);
                 ButtonText[i] = this.pluginLang.readPluginField("APPLANG/SETUP/DISPLAYNAME");
                 ButtonValue[i++] = this.pluginLang.readPluginField("APPLANG/HELLOWORLD/DISPLAYNAME");
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";

                 // BOOL BUTTONS (5-8)
 
                 ButtonHandler[i] = new SettingsClickHandler(SetLogEvents);
                 ButtonText[i] = this.pluginLang.readPluginField("/APPLANG/SETUP/LOGEVENTS");
                 ButtonValue[i++] = readConfig("/APPCONFIG/LOGEVENTS");
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
            }
         }
         else
         {
             /*******************************************************************************************/
             /*****  BASIC SETTINGS - PAGE 1  ***********************************************************/
             /*******************************************************************************************/
             if (currentpage == 1)
             {
 
                 // TEXT BUTTONS (1-4)
 
                 ButtonHandler[i] = new SettingsClickHandler(SetDisplayName);
                 ButtonText[i] = this.pluginLang.readPluginField("APPLANG/SETUP/DISPLAYNAME");
                 ButtonValue[i++] = this.pluginLang.readPluginField("APPLANG/HELLOWORLD/DISPLAYNAME");
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 // BOOL BUTTONS (5-8)
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
 
                 ButtonHandler[i] = null;
                 ButtonText[i] = "";
                 ButtonValue[i++] = "";
             }
         }
     }
     catch (Exception errmsg) { CFTools.writeError(errmsg.Message, errmsg.StackTrace); }
 }

Settings Fields Button Handlers

As shown in the readConfig() function above, button handlers must be set for all settings buttons in which users may change and/or enter data.
For boolean buttons, the handlers are almost always as simple aS setting the config value to the ToString() representation of the value parameter, the True/False value is represented by the value parameter (ref object value). This can be seen in the below example SetLogEvents().
For text field buttons, the value parameter is the index of the button array, thereby making it easy to move settings fields around in the readConfig() override. This can be seen in the below example SetDisplayName() in the line ButtonValue[(int)value] = resultvalue;.

 private void SetDisplayName(ref object value)
 {
     try
     {
         object tempobject;
         string resultvalue, resulttext;
         if (this.CF_systemDisplayDialog(CF_Dialogs.OSK, this.pluginLang.readPluginField("/APPLANG/SETUP/DISPLAYNAME"), ButtonValue[(int)value], null, out resultvalue, out resulttext, out tempobject, null, true, true, true, true, false, false, 1) == DialogResult.OK)
         {
             languagexml.SelectSingleNode("/APPLANG/HELLOWORLD/DISPLAYNAME").InnerText = HttpUtility.HtmlEncode(resultvalue);
             ButtonValue[(int)value] = resultvalue;
         }
     }
     catch (Exception errmsg) { CFTools.writeError(errmsg.Message, errmsg.StackTrace); }
 }

 private void SetLogEvents(ref object value)
 {
     updateConfig("/APPCONFIG/LOGEVENTS", value.ToString());
 }

OK and Cancel Button Handlers

Each setup dialog for a plugin shall implement it's own Save() and Cancel() routines to handle when a user clicks the Save button or Cancel button. Almost always a Cancel handler will just typically set the DialogResult to Cancel and return. But the Save handler should save the adjusted xml values to file.

 private void section1_CFSetup_ok(object sender, EventArgs e)
 {
     // Launches system YesNo dialog to verify the user wants to overwrite their current settings.  If yes then the
     // local XML document is saved.
     object tempobject;
     string temp, temp2;
     try
     {
         if (this.CF_systemDisplayDialog(CF_Dialogs.YesNo, LanguageReader.getText("APPLANG/SETUP/OVERWRITETEXT"), null, null, out temp, out temp2, out tempobject, null, true, true, true, true, false, false, 1) == DialogResult.OK)
         {
             configxml.Save(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData) + "\\Centrafuse\\" + PluginPath + ConfigurationFile);
             languagexml.Save(PluginPathLanguages + configxml.SelectSingleNode("/APPCONFIG/APPLANG").InnerText + ".xml");
             this.DialogResult = DialogResult.OK;
         }
     }
     catch (Exception errmsg) { CFTools.writeError(errmsg.Message, errmsg.StackTrace); }
 }

 private void section1_CFSetup_cancel(object sender, EventArgs e)
 {
     this.DialogResult = DialogResult.Cancel;
 }