Notebooks

The Notebook API lets you add and change entries in the BlackBerry Remember app on a device. This app 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 app 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.

The Notebook class represents a notebook in the Remember app. The NotebookEntry class represents a single notebook entry in a Notebook. 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.

Prerequisites

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

LIBS += -lbbpim

Your app must also have the Notebooks permission ( access_pimdomain_notebooks), which you specify in the bar-descriptor.xml file for your app.

Manipulating notebooks

To create a new notebook and add entries to it, you create a Notebook object and set its properties, such as name or other custom attributes that you specify. Then, you create NotebookEntry objects, set their properties, and add them to the notebook by calling NotebookService::addNotebookEntry(). You can also update an existing notebook in the notebook database using NotebookService::updateNotebook().

Not applicable

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.

#include <bb/pim/notebook/NotebookService>
#include <bb/pim/notebook/Notebook>
#include <bb/pim/notebook/NotebookEntry>
#include <bb/pim/notebook/NotebookId>

#include <bb/pim/account/AccountService>
#include <bb/pim/account/Service>

using namespace bb::pim::notebook;
using namespace bb::pim::account;
// 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 = myNotebook.id();

// 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
service.deleteNotebookEntry(secondEntry.id());

Handling errors

When you use the NotebookService to add, update, or delete 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.

Not applicable

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

#include <bb/pim/notebook/NotebookServiceResult>
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(secondEntry.id()) !=
    NotebookServiceResult::Success) {
    // Handle the error
}

Identifying notebooks and notebook entries

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.

Not applicable

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

#include <bb/pim/notebook/NotebookId>
#include <bb/pim/notebook/NotebookEntryId>

using namespace bb::pim::notebook;
NotebookId myNotebookId = myNotebook.id();
NotebookEntryId myNotebookEntryId = myNotebookEntry.id();

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.

Filtering notebook entries

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().

Not applicable

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.

#include <bb/pim/notebook/NotebookService>
#include <bb/pim/notebook/NotebookEntryFilter>
#include <bb/pim/notebook/NotebookEntryStatus>
#include <bb/pim/notebook/NotebookEntry>

using namespace bb::pim::notebook;
// Create the notebook service object
NotebookService service;

// Create the filter and set the appropriate criteria
NotebookEntryFilter filter;
filter.setStatus(NotebookEntryStatus::NotCompleted);

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

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus