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.

• The process
• Sample code
• Recommendations

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().
   • For BlackBerry devices operating on a CDMA network, AbstractPhoneListener.callAnswered() is only invoked for the first incoming call. To add data with subsequent incoming calls (that is, call waiting), when you override AbstractPhoneListener.callWaiting(), you must must initialize PhoneScreen to cover all combinations of screen orientation and call type: PORTRAIT/INCOMING, PORTRAIT/ACTIVECALL, LANDSCAPE/INCOMING, and LANDSCAPE/ACTIVECALL. Note: LANDSCAPE cases only need to be initialized if the device supports this type of orientation.
   • For devices operating on a GSM network, AbstractPhoneListener.callAnswered() is invoked for any incoming call. So, when you override AbstractPhoneListener.callIncoming(), you initialize PhoneScreen to cover PORTRAIT/INCOMING and LANDSCAPE/INCOMING combinations of screen orientation and call type. When you override AbstractPhoneListener.callAnswered(), you initialize PhoneScreen to cover PORTRAIT/ACTIVECALL and LANDSCAPE/ACTIVECALL combinations of screen orientation and call type. Note: LANDSCAPE cases only need to be initialized if the device supports this type of orientation.
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:

• Keep information that you add to a call screen simple. For example, a bitmap, an encoded image, or text.
• If you want to add a FieldManager, use either PhoneScreenHorizontalManager or PhoneScreenVerticalManager.
• If you want to add an image, invoke addImage(). An image can be a bitmap or an encoded image.
• If you want to add field objects and managers, invoke add().
• The field object cannot be a Screen or its child classes, an IllegalArgumentException will be thrown if the rule is not followed.
• Avoid adding interactive objects to a call screen. Field objects are converted to a bitmap and users cannot interact with them. For example, if you add a button, users cannot click the button.
• Do not add more than 500 Kb of information to the call screen. If you exceed this limit, the call screen does not display any of the information.
• Do not add more than 5 field objects to an instance of PhoneScreen, PhoneScreenHorizontalManager, or PhoneScreenVerticalManager.