HRBuckley.Net

This work is licenced under a Creative Commons Licence.

Quite often we want to be able to get some information from the user but don’t want to use the MainScreen interface. Instead we would rather use a Dialog. The built in Dialog API has some nice static functions that suspend the program execution until the user responds, then allows execution to continue. They handle all the tedious issues with the event thread for us. Wouldn’t it be nice to have a dialog that we could call to get some text, a phone number, or some other piece of information from the user? Well here is how you can do that:

/*
 * BasicTextDialog.java
 *
 * © Richard Buckley www.hrbuckley.net, 2010
 *
 * This work is licenced under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
 * To view a copy of this licence, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to
 * Creative Commons, 171 Second Street, Suite 300, San Francisco, California 94105, USA.
 */

package src.dialog;

import net.rim.device.api.ui.component.Dialog;
import net.rim.device.api.ui.component.DialogClosedListener;
import net.rim.device.api.ui.component.BasicEditField;
import net.rim.device.api.system.Bitmap;

//
//  Create a dialog with a BasicEditField to accept user input. This example sets the field style to
//  allow only uppercase input.
//
//
public class BasicTextDialog extends Dialog implements DialogClosedListener {
    private BasicEditField      _text;
    private int                 _choice;

    public BasicTextDialog()  {
        super(Dialog.D_OK_CANCEL, "Eenter Some Text.", Dialog.D_OK, Bitmap.getPredefinedBitmap(Bitmap.QUESTION), 0L);
        _text = new BasicEditField("Only Uppercase: ", null, BasicEditField.DEFAULT_MAXCHARS, BasicEditField.FILTER_UPPERCASE);
        add(_text);
        setDialogClosedListener(this);
    }

    //
    //   The dialogClosed listener is called when the user closes the dialog, we can get the selection made at this point.
    //
    public void dialogClosed(Dialog dialog, int choice) {
        _choice = choice;
    }

    //
    //   A static convenience function that takes care of creating the dialog, posting it as a modal window (this blocks
    //   our execution and gives the event thread back to the OS so the user can interact with our dialog).
    //
    public static String askForText() {
        BasicTextDialog nsd = new BasicTextDialog();
        nsd.doModal();

        //
        //    If the user selected OK return the content of the BasicEditField, otherwise return null
        //
        if (nsd._choice == Dialog.OK) {
            return nsd._text.getText();
        } else {
            return null;
        }
    }

    //
    //    This function move the focus to the BasicEditField when the dialog is attached to the UiEngine. If you don't
    //    do this the focus will go to the default button.
    //
    protected void onUiEngineAttached(boolean attached) {
        if (attached) {
            _text.setFocus();
        }
    }
}

Using the new dialog is very easy:

    String sometext = BasicEditDialog.askForText();

This work is licenced under a Creative Commons Licence.

The Blackberry JDE workspace for this program can be obtained using Git: git clone git://git.hrbuckley.net/BB/Lesson1/

Every Java source must be part of a package. Membership in a package has an impact on class scoping rules and permissions. Objects belonging to the same package will have different access rules applied with respect to each other than objects belonging to different packages. For this reason, a standard Blackberry device will not load modules with Classes declared in restricted packages. This prevents a malicious programmer from using the scoping and access rules of package membership to bypass Blackberry security. It is traditional that the file structure of a Java project reflect the package structure, but this is not enforced by RIM’s Java Development Environment (JDE). So the first decison we need to make is what Package we want out Class to belong to, and declare it in the source code:

package src.lessonOne;

Next we must import the declarations of all the classes we are going to use. Some classes seem to be automatically imported by the JDE, String for example, and need not be explicitly imported. It is probably a bad habit not to import these, but perhaps not my worst bad habit. A Blackberry program implementing a user interface must have at least one object that extends net.rim.device.api.ui.UiApplication so:

import net.rim.device.api.ui.UiApplication;

We can now declare our Class:

public class BasicGUI extends UiApplication {

}

Next we must tell the compiler how to start our program. The RIM compiler/linker will look for an object with a method called main declared public static void and taking a single String array as an argument. It will arrange for this method to be called when our program is launched. A minimal main method will instantiate our sub-class of UiApplication and call the inherited method enterEventDispatcher which will not normally return:

    public static void main(String[] args) {
        BasicGUI basicGUI = new BasicGUI();
        basicGUI.enterEventDispatcher();
    }

Add a simple constructor (which we will embelish later) and we have a complete, if not very useful Blackberry program:

/*
 * BasicGUI.java
 *
 * © Richard Buckley www.hrbuckley.net, 2010
 *
 * This work is licenced under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
 * To view a copy of this licence, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to
 * Creative Commons, 171 Second Street, Suite 300, San Francisco, California 94105, USA.
 */

package src.lessonOne;

import net.rim.device.api.ui.UiApplication;

/**
 *
 */
public class BasicGUI extends UiApplication {
    public static void main(String[] args) {
        BasicGUI basicGUI = new BasicGUI();
        basicGUI.enterEventDispatcher();
    }

    BasicGUI() {    }
}

The reason this program is not very useful is that, one of the things that enterEventDispatcher does, is monitor the number of Screens a UiApplication has pushed to the screen stack. We haven’t create any screens at all, so the program will exit directly. In my next post we will add a simple screen to our program.