The Notebook API lets you add and modify entries in the Remember application on a device. This application stores items in list-type structures called notebooks. Each notebook can contain a list of items or tasks called notebook entries. A notebook entry represents a single thought or action that a user might want to track. Users can use the Remember application to track any list-based information they want. A user might have one notebook for a to-do list, another notebook for a grocery list, and a third notebook for a list of gifts they'd like for their birthday.

Each notebook in the Remember application is represented by a Notebook object. Each of the notebook entries in a Notebook is represented by a NotebookEntry object. You can create new NotebookEntry objects with properties such as title, description, and due date, and then you can add these objects to a Notebook. There's also a special default notebook, which is created automatically, for unfiled notebook entries. You can use the default notebook to store entries that don't belong to any other notebooks. A notebook entry can belong to exactly one notebook at a time.

Diagram illustrating a Notebook object and a NotebookEntry object.

To use the Notebook API in your apps, you need to import the correct library by adding the following line to your project's .pro file:

LIBS += -lbbpim

Your app must also have the access_pimdomain_notebooks permission, which you specify in the bar-descriptor.xml file for your app. To learn more about the bar-descriptor.xml file, see The bar-descriptor.xml file.

Here's how to create a notebook and add two notebook entries to it. After the notebook entries are added, the second notebook entry is deleted from the notebook. To save your notebooks and notebook entries to the database, you need to create and use a NotebookService object.

// Retrieve the account key for the user account that's currently active on the
// device. This key is used when notebooks are added to the notebook database.
AccountKey accountKey = AccountService().defaultAccount( Service::Notebook ).id();

// Create the notebook service object. Make sure that you don't recreate this
// object each time you need to access the notebook service, though.
NotebookService service;

// Create the notebook and set its name
Notebook myNotebook;
myNotebook.setName("My Notebook");

// Add the new notebook to the database
service.addNotebook(&myNotebook, accountKey);

// Create the first notebook entry and set its title
NotebookEntry firstEntry;
firstEntry.setTitle("My First Notebook Entry");

// Create the second notebook entry and set its title
NotebookEntry secondEntry;
secondEntry.setTitle("My Second Notebook Entry");

// Retrieve the ID that was assigned to the new notebook. This ID is used to
// add the new notebook entries to the correct notebook.
NotebookId myNotebookId =;

// Add the new notebook entries to the notebook
service.addNotebookEntry(&firstEntry, myNotebookId);
service.addNotebookEntry(&secondEntry, myNotebookId);

// Perform other app-specific operations here
// ....

// Delete the second notebook entry from the database

Using the Notebook API

The following sections outline some important concepts about notebooks. You may find these concepts useful as you work with notebooks in your apps.

Handling errors

When you use the NotebookService to add, update, or remove notebooks and notebook entries, there are several errors that might occur. The Notebook or NotebookEntry that you specify might not exist, or the operation that you're trying to perform might not be allowed for the specified Notebook. These types of errors are defined in the NotebookServiceResult class, and you can use this class to make sure that your operations on the notebook database are successful.

For example, in the code sample above, you can check for an error when you call addNotebook() to make sure that the Notebook was added to the database successfully.

if (service.addNotebook(&myNotebook, accountKey) !=
    NotebookServiceResult::Success) {
    // Handle the error

Similarly, you can check for an error when you call addNotebookEntry() and deleteNotebookEntry().

if (service.addNotebookEntry(&firstEntry, myNotebookId) !=
    NotebookServiceResult::Success) {
    // Handle the error

// ...

if (service.deleteNotebookEntry( !=
    NotebookServiceResult::Success) {
    // Handle the error

Using notebook IDs and notebook entry IDs

Each Notebook and NotebookEntry includes an ID, represented by the NotebookId and NotebookEntryId classes, respectively. These IDs uniquely identify the Notebook or NotebookEntry, and are assigned when you add the Notebook or NotebookEntry to the database by using the NotebookService. When you perform operations on Notebook objects and NotebookEntry objects in your app, it's important that you specify the proper ID for the object that you want to manipulate.

You can retrieve the notebook ID and notebook entry ID by using the appropriate id() functions.

NotebookId myNotebookId =;
NotebookEntryId myNotebookEntryId =;

Using notebook entry statuses

Notebook entries can either be actionable or not actionable. Actionable notebook entries represent items that can be either completed or not completed. For example, entries like "Go to the grocery store" or "Pick up Trish from soccer practice" are actionable items. Other entries, such as "Ottawa is the capital of Canada" and "Shakespeare wrote plays" aren't (generally) actionable items.

You can use the NotebookEntryStatus::Type enumeration to represent the status of a notebook entry:

  • NotActionable for entries that are not actionable
  • NotCompleted for entries that are actionable but not completed
  • Completed for entries that are actionable and completed

By default, new NotebookEntry objects are NotCompleted.

Using notebook entry filters

There may be times when you want to search for a specific type of notebook entry or display only certain types of notebook entries in your app. For example, you might want to restrict your search to notebook entries that belong to a particular notebook, or display only the notebook entries that have a specific due date.

You can use a NotebookEntryFilter to specify criteria for a set of notebook entries that you're interested in. Then, when you want to retrieve the list of notebook entries that fit those criteria, you can call NotebookService::notebookEntries() and specify the NotebookEntryFilter as a parameter. You can also determine if a single NotebookEntry fits the criteria of a NotebookEntryFilter by calling NotebookEntryFilter::accepts().

Here's how to create a NotebookEntryFilter that accepts only notebook entries that have a status of NotCompleted. When this filter is passed to notebookEntries(), only those entries that are actionable but not completed are returned. Entries with other statuses aren't returned.

// Create the notebook service object
NotebookService service;

// Create the filter and set the appropriate criteria
NotebookEntryFilter filter;

// Retrieve the list of notebook entries that fit the filter's criteria
QList<NotebookEntry> entries = service.notebookEntries(filter);

Last modified: 2014-01-23

comments powered by Disqus