net.rim.blackberry.api.pdap
Interface BlackBerryMemo

All Superinterfaces:
PIMItem

public interface BlackBerryMemo
extends PIMItem

Represents a single memo in the default RIM BlackBerryMemo database.

The fields supported by a given instance of a BlackBerryMemo object are defined in the BlackBerryMemoList object associated with the memo. The BlackBerryMemoList restricts which fields are retained by a BlackBerryMemo database. If a BlackBerryMemoList encounters a BlackBerryMemo object that contains unsupported fields, those fields are dropped.

The PIMList.isSupportedField(int) method is invoked to determine if a field (as specified by the integer argument) is supported by a BlackBerryMemoList. Similarly, the PIMList.getSupportedFields() method is invoked to return an integer array representing all fields supported by the list.

Data

The following table details the explicitly-defined fields that may be in a BlackBerryMemo.

Fields Type of Data Associated with Field
NOTE, TITLE, UID PIMItem.STRING

Working with the BlackBerryMemo object

The following examples demonstrate how to use the BlackBerryMemo object.

Below, a new memo is created and given the category "Work".

         try {
             BlackBerryMemo memo = memoList.createMemo();
             memo.addToCategory( "Work" );
         } catch( PIMException e ) {
             // BlackBerryMemo could not be created        
         }     
 

To delete the the BlackBerryMemo from the list, use the remove() method.

         memoList.removeMemo( memo );
 
Adding data to a BlackBerryMemo object

When adding data to a BlackBerryMemo, you first need to ensure that the field and attribute you are adding are supported by the list. Below, the isSupportedField() method is used to determine whether or not the specified field is supported. If the specified field is supported the data will be added to the memo.

Below, a title and notes are given to the BlackBerryMemo object. Note that each field takes a String. An exception will be thrown if an incorrect data type is specified and added to the field.

         if ( memoList.isSupportedField( BlackBerryMemo.TITLE ) ) {
             memo.addString( BlackBerryMemo.TITLE, 0, "New Company Policy" );
         }
         if ( memoList.isSupportedField( BlackBerryMemo.NOTE ) ) {
             memo.addString( BlackBerryMemo.NOTE, 0, "Here are the details..." ); 
         }
 

Updating data in an existing BlackBerryMemo object

The previous example added new data to an empty field. Since you cannot add data to a field that already contains data, the countValues() method is invoked to determine if the field is not empty, and the removeValue() method is used to remove the data from the field before adding the updated data with the addString() method.

         if ( memo.countValues( BlackBerryMemo.NOTE ) > 0 ) {
             memo.removeValue( BlackBerryMemo.NOTE, 0 );
         }
         memo.addString( BlackBerryMemo.NOTE, 0, "These are the updated details...");
 

Alternatively, the setString() method can be used to change the value of a string that already exists in the BlackBerryMemo.

         if ( memo.countValues( BlackBerryMemo.NOTE ) > 0 ) {
             memo.setString( BlackBerryMemo.NOTE, 0, 0, "These are the updated details..." );
         }
 

Saving a BlackBerryMemo object

The commit() method must be used to save the object to a list. Below, the isModified() method is called to determine whether or not the BlackBerryMemo's information has been modified. If so, the commit() method is invoked and the memo is saved.


         if( memo.isModified() ) {
             memo.commit();
         }
 

A BlackBerryMemo cannot be saved unless its TITLE field is set. If you invoke commit() on a BlackBerryMemo object whose TITLE field is not set, the method will throw a PIMException. This exception indicates that the commit failed because the TITLE field is not set. If you load a BlackBerryMemo by invoking BlackBerryMemoList.items(), it is guaranteed that the BlackBerryMemo's TITLE field will be set.

Accessing the MemoPad database

This interface allows developers to manipulate the "memos" database: the database used by the BlackBerry MemoPad application. Use an implementation of this interface to add, remove, or update memos in an application. Modifications to the memo database are visible through the MemoPad application. Listeners can be registered to notify an application when the memo database is modified. Changes to the MemoPad database through this interface are synchronized wirelessly with the clientís Outlook/Notes server.

For more information about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

See Also:
PIMItem, BlackBerryMemoList
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

Field Summary
Category: Signed static int NOTE
          Field representing the memo's note.
Category: Signed static int TITLE
          Field representing the memo's title.
Category: Signed static int UID
          Field representing the memo's unique ID.
 
Fields inherited from interface javax.microedition.pim.PIMItem
ATTR_NONE, BINARY, BOOLEAN, DATE, EXTENDED_ATTRIBUTE_MIN_VALUE, EXTENDED_FIELD_MIN_VALUE, INT, STRING, STRING_ARRAY
 
Method Summary
 
Methods inherited from interface javax.microedition.pim.PIMItem
addBinary, addBoolean, addDate, addInt, addString, addStringArray, addToCategory, commit, countValues, getAttributes, getBinary, getBoolean, getCategories, getDate, getFields, getInt, getPIMList, getString, getStringArray, isModified, maxCategories, removeFromCategory, removeValue, setBinary, setBoolean, setDate, setInt, setString, setStringArray
 



Field Detail

NOTE

static final int NOTE
Field representing the memo's note.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

TITLE

static final int TITLE
Field representing the memo's title.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

UID

static final int UID
Field representing the memo's unique ID.

The unique ID field is valid only if the event has been added to a BlackBerryMemoList at least once in the past. If the BlackBerryMemo has not yet been added to a list, the UID returns null.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0





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.