PluginDevGuide ConfigurationPage

From VuzeWiki
Jump to: navigation, search
You can download the code for this tutorial here. The JAR file can be opened in any program which can open up ZIP files, and contains both the compiled code and the source code.
Version: 0.4
Link: Download
Description: Plugin with configuration panel.

Plugin Development Guide: Creating a configuration page[edit]

Creating a config section[edit]

Now we are going to concentrate on how to create a configuration page for your plugin. Your plugin can consist of several configuration sections if you want, but we will concentrate on one page for the moment.

The BasicPluginConfigModel interface represents a configuration section. To create one, we just need to write this:

  BasicPluginConfigModel config_page =
     plugin_interface.getUIManager().createBasicPluginConfigModel("aizen");

When we do that, we get the following result:

PluginDevGuide ConfigurationPage 1.png

As you can see - the config section appears, but doesn't have any content (as you might expect). You might also notice the name of the configuration section: !ConfigView.section.aizen!. As you might have realised from our previous section on localising text, we have to define a text definition for the name to be localised (the Javadoc for the createBasicPluginModel method told us that).

Adding labels[edit]

Now we want to populate the configuration page with something meaningful. I'll start off with some text. Everything you create on the page is in the form of a "parameter", even if it is just a label. We'll start off by adding a label, and a hyperlink to this development guide.

  config_page.addLabelParameter2("aizen.config.title");
  config_page.addHyperlinkParameter2("aizen.config.wiki_link",
      "http://www.azureuswiki.com/index.php/Plugin_Development_Guide");

We'll then define the resource definitions here:

aizen.config.title=Aizen - Example Plugin
aizen.config.wiki_link=Plugin Development Guide

These changes give us this:

PluginDevGuide ConfigurationPage 2.png

Adding configuration parameters[edit]

So to add anything to the configuration page - we add a parameter. Of course, the whole point of a configuration page is usually to allow something to be configured. So let's try to make something configurable - like the changing of the download speed limit we added before here.

We'll change the line here:

  pconfig.setCoreIntParameter(PluginConfig.CORE_PARAM_INT_MAX_DOWNLOAD_SPEED_KBYTES_PER_SEC, 25);

To this instead:

  int down_speed_limit = pconfig.getPluginIntParameter("down speed limit", 25);
  pconfig.setCoreIntParameter(PluginConfig.CORE_PARAM_INT_MAX_DOWNLOAD_SPEED_KBYTES_PER_SEC, down_speed_limit);

This then takes the parameter value stored with the plugin, and set the download speed limit with it (defaulting to 25 if it isn't defined). Of course, this isn't actually of any use unless we provide the user with a way to modify the plugin value - so here's the line to do it.

  config_page.addIntParameter2("down speed limit", "aizen.config.down_speed_limit", 25);

Now, here's the important things to remember. When you create a parameter in this way, it will get stored as a plugin parameter value. We use the same name ("down speed limit") when we both access it via the PluginConfig model and when we create the parameter. Most parameters take a message key to be used as the label - that's the second parameter we pass in. The third parameter is usually the default value for the parameter.

It might seem a bit inconvenient for you to pull values from PluginConfig when you have parameter objects available - well, you're right. We do it in this example, just because the parameters haven't been created by the time we are setting the download speed. But if we re-order the code, such that we create the config model before setting the download limit, then we can do this:

  // Create the configuration section.
  BasicPluginConfigModel config_page = plugin_interface.getUIManager().createBasicPluginConfigModel("aizen");
  config_page.addLabelParameter2("aizen.config.title");
  config_page.addHyperlinkParameter2("aizen.config.wiki_link",
      "http://www.azureuswiki.com/index.php/Plugin_Development_Guide");

  // Create a parameter to change the download speed...
  IntParameter down_speed_param = config_page.addIntParameter2(
      "down speed limit", "aizen.config.down_speed_limit", 25);

  // And grab the value from the parameter object itself, and modify the download speed.
  pconfig.setCoreIntParameter(PluginConfig.CORE_PARAM_INT_MAX_DOWNLOAD_SPEED_KBYTES_PER_SEC ,
      down_speed_param.getValue());

As this "set download limit" behaviour on startup can be annoying, we'll add a checkbox to toggle if it is enabled or not.

So we create a checkbox parameter to control if it is enabled. We'll define it before we define the down speed limit parameter, because we want the checkbox to appear before the speed parameter (the order in which you create the parameters is the order in which it will appear).

   // Indicates if the change-on-speed behaviour is enabled or not. By default,
   // it isn't.
   BooleanParameter enabled_param = config_page.addBooleanParameter2(
       "down speed limit enabled", "aizen.config.down_speed_limit", false);
   // Create a parameter to change the download speed...
   IntParameter down_speed_param = config_page.addIntParameter2(
       "down speed limit", "aizen.config.down_speed_limit", 25);
   // And grab the value from the parameter object itself, and modify the download speed.
   // But only if enabled!
   if (enabled_param.getValue()) {
       pconfig.setCoreIntParameter(PluginConfig.CORE_PARAM_INT_MAX_DOWNLOAD_SPEED_KBYTES_PER_SEC ,
           down_speed_param.getValue());
   }

Interacting[edit]

As a nice touch, we'll add some desirable UI behaviour - when it's disable, we'll grey out the speed limit entry box. We can actually achieve this in just one line of code:

   // This will only make the download speed parameter usable if the enabled parameter is available.
   enabled_param.addEnabledOnSelection(down_speed_param);

This is a simple example of interacting with the parameter objects that you create. Not only can you get and set the values of parameters, and define some UI behaviour (like I've just shown you) - but you can listen for when a value has been changed or when a parameter has been interacted with. We'll add one which changes the down speed limit on demand (by using a push button).

   // Push button to set the download speed value when the button is pushed.
   ActionParameter do_it_now_button = config_page.addActionParameter2(
       "aizen.config.do_it_now.label", "aizen.config.do_it_now.button");
   do_it_now_button.addListener(new ParameterListener() {
       public void parameterChanged(Parameter p) {
           pconfig.setCoreIntParameter(PluginConfig.CORE_PARAM_INT_MAX_DOWNLOAD_SPEED_KBYTES_PER_SEC ,
               down_speed_param.getValue());
           }
       });

What we do here, is create a push button. When it gets pushed, it generates an event saying that something has changed (we get similar events when the value of other parameters are modified). When we get that event, we read the value of our download speed limit parameter, and then set the download speed limit via the PluginConfig object.

In case you're wondering what our plugin looks like now...

PluginDevGuide ConfigurationPage 3.png

Summary[edit]

This gives you a quick overview of how to create configuration sections - commonly you need one line of code to create each component of the configuration section, and one line to define the readable text... and presumably several lines to do something interesting with it. :)

Once these parameters are created - that's it. You don't need to do anything to handle saving of values, or loading up existing values - it's done for you. This shows you how straight-forward it is to add UI configuration components (and how to react to those changes).