Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Custom buttons sample app

The custom buttons sample application demonstrates how to extend the Field class to create a variety of different button UI components.

The sample application demonstrates how to create the following types of buttons:
  • rectangle
  • triangle
  • octagon
  • rectangle with a fixed width
  • rectangle with a fixed width and a long text label
  • rectangle with a full screen width
  • rectangle with a color background
  • rectangle with a .bmp image as the background

In addition to creating and displaying these custom buttons, the sample application also demonstrates how to attach listeners to these custom buttons. Listeners are components that execute code when an event occurs. In the sample application, when you click one of these buttons, a dialog box appears with text specifying which of the buttons you clicked.

Filename

Description

CustomButtonsDemo.java

The application, which includes the entry point that starts the screen, creates and adds each of the UI components, and adds the application to the Event Dispatcher.

CustomButtonField.java

This class provides constructors to create a custom button that is a rectangle, a triangle, an octagon, a rectangle with a fixed width, a rectangle with a fixed width that has a long text label, a rectangle with a full screen width, or a rectangle with a background of a specified color.

This class extends the Field class and overrides the getPreferredHeight() and getPreferredWidth() methods. These methods use the size of the text label to return a height and width to create a custom button that fully encapsulates the text label.

This class also overrides the Field class methods drawFocus(Graphics, boolean), layout(int, int), and paint(Graphics) to render the specific shapes and styles.

PictureBackgroundButtonField.java

This class provides methods to create a custom button with a Bitmap as its background. This class also extends the Field class but (unlike the CustomButtonField class), this class does not implement the DrawStyle interface. This is because this class does not need the text alignment and position constants that the DrawStyle interface provides.

There are two Bitmap objects (defined within the class, not in the constructor), for when the button is in focus or not in focus. The switching of these Bitmap objects is managed by the overridden onFocus() and onUnfocus() methods from the Field class.

Similar to the CustomButtonField class, the PictureBackgroundButtonField class overrides the getPreferredHeight(), getPreferredWidth(), layout(int, int), and paint(Graphics) methods from the Field class to manage the rendering of the PictureBackgroundButtonField object. However, since the switching of the background image on focus is already managed by the onFocus() and onUnfocus() methods, the drawFocus(Graphics, boolean)does not need to perform any actions.

img/bluescribble.bmp

This is a .bmp file that the PictureBackgroundButtonField object uses as the background when the button is not in focus.

img/pinkscribble.bmp

This is a .bmp file that the PictureBackgroundButtonField object uses as the background when the button is in focus.

This sample features the following classes:

net.rim.device.api.ui.Field

This class provides the fundamental functionality for all UI components. All the built-in components you can add to a Screen are subclasses of the Field class. You cannot create the Field class directly; you must either use one of the implemented subclasses or extend this class to create your own custom component.

In the sample application, the subclasses of the of the Field class are the CustomButtonField, (which you use to create all the custom buttons except for the button with an image as its background), and the PictureBackgroundButtonField class.

Install the sample app

Visit http://www.blackberry.com/go/custombuttonssample to download the sample application.

Extract the custombuttonsdemo.zip file.

On the taskbar, click Start > Programs > Research In Motion > BlackBerry JDE 4.7.0 > JDE.

Open the workspace that you want to add the sample application to.

In the workspace tree, right-click the project that you want to add the sample application to.

Click Add project to <workspace directory> .

In the Add project to <workspace> dialog box, browse to the folder where you extracted the sample application.

Click the CustomButtonsDemo.jdp file.

Click Open.

The sample app is also available in github.

Run the sample app

In the workspace where you added the custombuttonsdemo project, right-click custombuttonsdemo.

Click Build project.

On the taskbar, click Start > Applications > Research in Motion > BlackBerry JDE 4.7.0 > Device Simulator.

On the Home screen of the BlackBerry Smartphone Simulator, click the Downloads folder.

Click the Custom Buttons Demo icon.