Package net.rim.blackberry.api.phone.phonegui

Provides classes to display information on the incoming and active call screens

See:
          Description

Class Summary
PhoneScreen Provides the ability to display information on the incoming and active call screens on a BlackBerry device.
PhoneScreenHorizontalManager Manager used to organize data horizontally onto the phone screen.
PhoneScreenVerticalManager Manager used to organize data vertically onto the phone screen.
ScreenModel Provides the ability to initialize PhoneScreen objects so that you can display information on the incoming and active call screens.
 

Package net.rim.blackberry.api.phone.phonegui Description

Provides classes to display information on the incoming and active call screens.

Overview

On BlackBerry® devices that are running BlackBerry® Device Software 5.0 or later, you can uses the classes in this package to customize the incoming and active call screens to display information on the lower part of the phone screen. For example, for an incoming call from a contact on the device, you can display additional information about the contact.

Permissions

An application control policy can determine if information can be displayed on a BlackBerry device that is locked. This API verifies whether data can be displayed on a device that is locked regardless if the device is actually locked or not. You can also invoke PhoneScreen.isSupported() to check this policy.

Layout

By default when you add UI fields to a phone screen, they are centered on the screen. You can change the alignment by adding your UI fields to a PhoneScreenHorizontalManager and then add the manager to the phone screen.

The process

To add data to a phone screen:

  1. Extend AbstractPhoneListener.
  2. Register the phone listener (for example, Phone.addPhoneListener(phoneListener)).
  3. Override the phone listener's callIncoming(), callWaiting(), callInitiated(), and callAnswered() callback methods and initialize an instance of PhoneScreen by invoking ScreenModel.getPhoneScreen().
  4. Add your data to the PhoneScreen by invoking PhoneScreen.add().
  5. Add your data to the incoming or active call screens by invoking ScreenModel.sendAllDataToScreen().
  6. Optionally register the phone listener on startup, and then keep it around as long as the device is running. An application can choose to deregister itself from the phone listener before it is closed.

Sample code

The following code sample is an example implementation of PhoneListener.callIncoming(). The sample adds label fields to the incoming call screen by overriding AbstractPhoneListener.callIncoming(). It checks the orientation of the screen before adding objects to the call screen. See the notes above about covering calls on CDMA devices.

 public void callIncoming(int callId)
 {
    // Obtain ScreenModel for current call.
    ScreenModel screenModel = new ScreenModel(callId);
    
    // Obtain PhoneScreen in portrait mode for incoming call screen.
    PhoneScreen phoneScreenPortrait = screenModel.getPhoneScreen(PhoneScreen.PORTRAIT, PhoneScreen.INCOMING);
    
    // Create labels to be added to the phone screen.
    LabelField labelField1 = new LabelField("Hello") {
        public void paint(Graphics g) {
            g.setColor(Color.GREEN);
            g.setBackgroundColor(Color.CORAL);
            g.clear();
            super.paint(g);
        }
    };    
    
    LabelField labelField2 = new LabelField(" to the World. ") {
        public void paint(Graphics g) {
           g.setColor(Color.RED);
           super.paint(g);
        }
    };
    
    // Set the font of the label fields to be the same as that of the
    // caller info displayed on the screen by the Phone application.
    labelField1.setFont(phoneScreenPortrait.getCallerInfoFont());
    labelField2.setFont(phoneScreenPortrait.getCallerInfoFont());
    
    // Add labels to the PhoneScreen
    phoneScreenPortrait.add(labelField1);
    phoneScreenPortrait.add(labelField2); 
    
    // Obtain PhoneScreen in landscape mode for incoming call screen.
    PhoneScreen phoneScreenLandscape = screenModel.getPhoneScreen(PhoneScreen.LANDSCAPE, PhoneScreen.INCOMING);
    
    // If phoneScreenLandscape is null, the device is not rotatable.
    if (phoneScreenLandscape !=null) {
        
        // Create labels to be added to the phone screen.
        LabelField labelField3 = new LabelField("Hello") {
            public void paint(Graphics g) {
                g.setColor(Color.CHOCOLATE);
                g.setBackgroundColor(Color.YELLOW);
                g.clear();
                super.paint(g);
            }
        };
        
        LabelField labelField4 = new LabelField(" to the World. ") {
            public void paint(Graphics g) {
                g.setColor(Color.YELLOW);
                super.paint(g);
             }
        };
        
        // Add padding to label fields.
        labelField3.setPadding(0, 5, 0, 10);
        labelField4.setPadding(0, 10, 0, 5); 
        
        // Initialize a PhoneScreenHorizontalManager and add label fields.
        PhoneScreenHorizontalManager phoneScreenHorizontalManager = new PhoneScreenHorizontalManager();        
        phoneScreenHorizontalManager.add(labelField3);
        phoneScreenHorizontalManager.add(labelField4);
        
        // Center the PhoneScreenHorizontalManager. UI fields
        // are centered in the PhoneScreen by default with the
        // exception of PhoneScreenHorizontalManager.         
         XYRect xyRect = phoneScreenLandscape.getDimensions();
        int padPoint = (xyRect.width - phoneScreenHorizontalManager.getPreferredWidth()) / 2;
        if (padPoint > 0) {
            phoneScreenHorizontalManager.setPadding(0, padPoint, 0, padPoint);
        }
        
        // Add the PhoneScreenHorizontalManager to the PhoneScreen.
        phoneScreenLandscape.add(phoneScreenHorizontalManager);
    }
    
    // Send data contained in ScreenModel to the screen.
    screenModel.sendAllDataToScreen();
 }
 

Recommendations:






Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.