The Options application – or Settings on some BlackBerry themes – provides a unified location to set BlackBerry options and configure applications. A BlackBerry application can also add its own options to this listing, allowing a user to configure an application from outside of the application. This can be very useful for background applications that do not use a graphical user interface (GUI). The sample application below shows how to add custom options to the BlackBerry Options application by using the OptionsManager class and the OptionsProvider interface.

Note: This sample application uses an alternate entry point that specifies “auto-start” as its parameter. For more information on alternate entry points, see this article .

OptionsSample.java

package com.rim.samples.options;

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.system.*;
import net.rim.blackberry.api.options.*;

public class OptionsSample extends UiApplication
{
    public static void main(String[] args)
    {
        //This sample makes use of alternate entry points.
        //An alternate entry point will need to be configured
        //in your workspace to use this sample.

        if (args.length > 0 && args[0].equals("auto-start"))
        {
            //Enter the auto start portion of the application.
            //Register an options provider and exit.
            OptionsSampleOptionsProvider provider =
              new OptionsSampleOptionsProvider();
            OptionsManager.registerOptionsProvider(provider);
        }
        else
        {
            //Enter the GUI portion of the applicaiton.
            //Create a new instance of the application
            //and start the application on the event thread
            OptionsSample theApp = new OptionsSample();
            theApp.enterEventDispatcher();
        }
    }

    public OptionsSample()
    {
        MainScreen theScreen = new MainScreen();
        theScreen.setTitle(new LabelField("Options Sample"));
        OptionsSampleProperties props = OptionsSampleProperties.fetch();
        RichTextField greeting = new RichTextField();

        if (props.isGreetingEmphasized())
        {
            // An emphatic greeting is in all capitals and followed by
            // exclamation marks and is displayed in bold.
            String greetingText = props.getGreeting().toUpperCase()
              + "!!!!";
            Font emphatic = Font.getDefault().derive(Font.BOLD);
            int[] offsets = {0, greetingText.length()};
            byte[] attributes = {0};
            Font[] fonts = {emphatic};
            greeting.setText(greetingText, offsets, attributes, fonts);
        }
        else
        {
            greeting.setText(props.getGreeting());
        }

        theScreen.add(greeting);
        pushScreen(theScreen);
    }
}

OptionsSampleOptionsProvider.java

package com.rim.samples.options;

import net.rim.blackberry.api.options.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.*;

class OptionsSampleOptionsProvider implements OptionsProvider
{
    private EditField greetingEdit;
    private ObjectChoiceField styleChoice;
    private OptionsSampleProperties optionProperties;

    public OptionsSampleOptionsProvider()
    {
    }

    public String getTitle()
    {
        return "Options Sample";
    }

    public void populateMainScreen(MainScreen mainScreen)
    {
        //Read in the properties from the persistent store.
        optionProperties = OptionsSampleProperties.fetch();

        //Get the current values from optionProperties and create
        //the controls to represent them.
        greetingEdit = new EditField
          ("Greeting: ", optionProperties.getGreeting(),
            BasicEditField.DEFAULT_MAXCHARS, BasicEditField.NO_NEWLINE);
        mainScreen.add(greetingEdit);

        Object[] choices = {"Normal", "Emphatic!!"};
        int selection = optionProperties.isGreetingEmphasized() ? 1 : 0;
        styleChoice = new ObjectChoiceField("Style: ", choices, selection);
        mainScreen.add(styleChoice);
    }

    public void save()
    {
        //Get the new values from the UI controls
        //and set them in optionProperties.
        optionProperties.setGreeting(greetingEdit.getText());
        optionProperties.setGreetingEmphasized
          (styleChoice.getSelectedIndex() != 0);

        //Write our changes back to the persistent store.
        optionProperties.save();

        //Null out our member variables so that their objects can be garbage
        //collected. Note that this instance continues to be held by the
        //options manager even after the user exits the options app,
        //and will be re-used next time.

        greetingEdit = null;
        styleChoice = null;
        optionProperties = null;
    }
}

OptionsSampleProperties.java

package com.rim.samples.options;

import net.rim.device.api.system.*;
import net.rim.device.api.util.*;

//The configuration properties of the OptionsSample application. One instance holding
//the effective values resides in the persistent store.
class OptionsSampleProperties implements Persistable
{
    private String greeting;
    private boolean greetingEmphasized;

    //Hash of com.rim.training.options.OptionsSampleProperties
    private static final long PERSISTENCE_ID = 0x7eeffcc691f4418dL;

    //Persistent object wrapping the effective properties instance
    private static PersistentObject store;

    //Ensure that an effective properties set exists on startup.
    static {
        store = PersistentStore.getPersistentObject(PERSISTENCE_ID);
        synchronized (store) {
            if (store.getContents() == null) {
                store.setContents(new OptionsSampleProperties());
                store.commit();
            }
        }
    }

    // Constructs a properties set with default values.
    private OptionsSampleProperties()
    {
        greeting = "Hello there";
        greetingEmphasized = false;
    }

    //Retrieves a copy of the effective properties set from storage.
    public static OptionsSampleProperties fetch()
    {
        synchronized (store)
        {
            OptionsSampleProperties savedProps =
              (OptionsSampleProperties) store.getContents();
            return new OptionsSampleProperties(savedProps);
        }
    }

    //Causes the values within this instance to become the effective
    //properties for the application by saving this instance to the store.
    public void save()
    {
        synchronized (store)
        {
            store.setContents(this);
            store.commit();
        }
    }

    //The greeting is the text that is displayed within the
    //OptionsSample application.
    public String getGreeting()
    {
        return greeting;
    }

    public void setGreeting(String greetingLocal)
    {
        greeting = greetingLocal;
    }

    //If emphasized, the greeting is displayed in more resouding manner.
    public boolean isGreetingEmphasized()
    {
        return greetingEmphasized;
    }

    public void setGreetingEmphasized(boolean greetingEmphasizedLocal)
    {
        greetingEmphasized = greetingEmphasizedLocal;
    }

    //Cannonical copy constructor.
    private OptionsSampleProperties(OptionsSampleProperties other)
    {
        greeting = other.greeting;
        greetingEmphasized = other.greetingEmphasized;
    }
}

[1] http://supportforums.blackberry.com/t5/Java-Development/Add-application-options-to-the-BlackBerry-Options/ta-p/442859