Notebook

Since: BlackBerry 10.0.0

#include <bb/pim/notebook/Notebook>

To link against this class, add the following line to your .pro file: LIBS += -lbbpim

The Notebook class represents a folder-like object that contains notebook entries.

Notebooks are used to organize actionable and non-actionable items called notebook entries into separate folders or topics. For example, you can create a "grocery list" notebook that contains items you need to purchase, each of which can be marked as completed as it is added to your cart. Notebooks can also contain non-actionable notebook entries, such as photos taken on a trip. Notebook entries are represented by the NotebookEntry class.

Some notebooks are created automatically by the system and have special meaning and behavior. Such special notebooks can be recognized by querying their Notebook::type() function, which will return something other than Notebook::Generic. Items in a non-generic notebook are generally kept in sync with another source, such as an ActiveSync account. See the Notebook::Type enum for supported special notebook types.

Example usage:
// Here's how to create a Notebook with a name and custom attribute, and add
// it to the default Notebook account database using the NotebookService.
// Note that service objects are potentially expensive to initialize, so you
// should not create them on a per-use basis as is done below.
AccountKey defaultAccountKey = AccountService().defaultAccount(
                                                 Service::Notebook ).id();
Notebook notebook;
notebook.setName( "New Notebook" );
notebook.setAttribute( "my_attribute", "my_attribute_value" );

// You should be sure to check the return code from addNotebook() for
// success
NotebookService().addNotebook( &notebook, defaultAccountKey );
See also:

NotebookEntry


Overview

Public Types Index

enum Type

Generic = 0, ActiveSyncMemo = 1, ActiveSyncTask = 2, Evernote = 4

Public Functions Index

Notebook ()
Notebook (NotebookDomain::Type domain)
Notebook (const Notebook &other)
~Notebook ()
boolallowAddNotebookEntry () const
QStringattribute (const QString &key) const
QMap< QString, QString >attributes () const
NotebookDomain::Typedomain () const
boolhasConstraint (NotebookConstraint::Type constraint) const
boolhasNotebookEntryConstraint (NotebookEntryConstraint::Type constraint) const
NotebookIdid () const
boolisDeletable () const
boolisReadOnly () const
boolisValid () const
QStringname () const
booloperator!= (const Notebook &other) const
Notebook &operator= (const Notebook &other)
booloperator== (const Notebook &other) const
voidresetAttribute (const QString &key)
voidsetAttribute (const QString &key, const QString &value)
voidsetDomain (NotebookDomain::Type domain)
voidsetName (const QString &name)
Typetype () const

Public Types

Type

An enumeration of supported Notebook types.

Notebooks with a type other than Notebook::Generic have special meaning and behavior. See the class-level documentation for more details.

Since:

BlackBerry 10.0.0

Generic = 0

The generic Notebook type, which implies no special meaning or behavior.

ActiveSyncMemo = 1

An ActiveSync Memo Notebook type, in which each contained NotebookEntry is synchronized with an ActiveSync Memo.

Since:

BlackBerry 10.0.0

ActiveSyncTask = 2

An ActiveSync Task Notebook type, in which each contained NotebookEntry is synchronized with an ActiveSync Task.

Since:

BlackBerry 10.0.0

Evernote = 4

An Evernote Notebook type, in which each contained NotebookEntry is synchronized with an Evernote entry.

Since:

BlackBerry 10.0.0

Public Functions

Notebook ()

Constructs a new Notebook with default values.

A default-constructed Notebook is considered invalid until at least one of its values is set. You can determine whether a Notebook is valid by calling isValid().

See also:

isValid()

Since:

BlackBerry 10.0.0

Notebook (

Constructs a new Notebook with the domain set to domain.

Since:

BlackBerry 10.3.0

Notebook (

Copy constructor.

This function constructs a Notebook containing exactly the same values as the provided Notebook.

Parameters
other

The Notebook to be copied.

Since:

BlackBerry 10.0.0

~Notebook ()

Destructor.

Since:

BlackBerry 10.0.0

bool allowAddNotebookEntry ()

Indicates whether new NotebookEntry objects can be added or moved to this Notebook.

Notebook entries cannot be added or moved to some system-created notebooks. Any attempt to add or move an entry to these notebooks via NotebookService::addNotebookEntry() will be rejected with an error code of NotebookServiceResult::ParentNotebookNotAllowed. You should query this function before attempting to add or move a notebook entry to a notebook, and UIs should query this function to determine whether to present an add or move operation to the user.

Return:

true if NotebookEntry objects can be added or moved to this Notebook, false otherwise.

Since:

BlackBerry 10.0.0

QString attribute (

Retrieves an attribute from this Notebook.

You can retrieve an attribute that was previously set on this Notebook.

Parameters
key

The key of the attribute to retrieve.

Return:

The value of the attribute, or a null (default-constructed) QString if no attribute value exists for this key.

Since:

BlackBerry 10.0.0

QMap< QString, QString > attributes ()

Retrieves all the attributes for this Notebook.

You can retrieve a QMap representing all attributes that are set on this Notebook.

Return:

A QMap of all attributes set on this Notebook.

Since:

BlackBerry 10.0.0

NotebookDomain::Type domain ()

Retrieves the domain of this Notebook.

The domains of notebooks are described in the NotebookDomain::Type enumeration.

Return:

The domain of this Notebook.

Since:

BlackBerry 10.3.0

bool hasConstraint (

Indicates whether this Notebook has the provided constraint.

Some system-created notebooks have constraints on their properties. These are soft constraints, meaning that invocations of NotebookService::updateNotebook() will not fail if the constraints are violated. Instead, those portions of the update that violate a constraint will be ignored.

For example, consider a Notebook whose name is not editable. If an update is done on that Notebook where its name is changed and an attribute is added, then the new attribute will be persisted but the new name will not.

You can use this function to determine how to present an edit UI to the user. For example, given a Notebook whose name is not editable, the edit UI should prevent the user from editing the name instead of letting NotebookService silently enforce that constraint.

Parameters
constraint

The constraint being checked.

Return:

true if this Notebook has the provided constraint, false otherwise.

Since:

BlackBerry 10.0.0

bool hasNotebookEntryConstraint (

Indicates whether this Notebook imposes the provided constraint on its notebook entries.

Some system-created notebooks impose constraints the properties of their contained NotebookEntry objects. These are soft constraints, meaning that invocations of NotebookService::addNotebookEntry() and NotebookService::updateNotebookEntry() will not fail if the constraints are violated. Instead, those portions of the add or update operations that violate a constraint will be ignored or made to agree with the violated constraint.

For example, consider a Notebook that imposes the constraint that the statuses of its NotebookEntry objects must be "not actionable". If a NotebookEntry with an actionable status (that is, "not completed" or "completed") is added to this type of Notebook, then its status will be persisted as "not actionable".

You can use this function to determine how to present an add or edit UI to the user. For example, given a NotebookEntry that does not support attachments, the add or edit UI should prevent the user from manipulating attachments instead of letting NotebookService silently enforce that constraint.

Parameters
constraint

The notebook entry constraint being checked.

Return:

true if this Notebook has the provided constraint on its notebook entries, false otherwise.

Since:

BlackBerry 10.0.0

NotebookId id ()

Retrieves the ID of this Notebook.

The ID uniquely identifies a Notebook in a particular account. The ID is assigned automatically by the database when a Notebook is added using the NotebookService. You can't set the ID of a Notebook manually.

Return:

The ID of this Notebook.

Since:

BlackBerry 10.0.0

bool isDeletable ()

Indicates whether this Notebook can be deleted.

Some system-created notebooks do not allow themselves to be deleted. Any attempt to delete this type of Notebook using NotebookService::deleteNotebook() will be rejected with an error code of NotebookServiceResult::OperationNotAllowed. You should query this function before attempting to delete a Notebook, and UIs should query this function to determine whether to present a delete operation to the user.

Note that unlike Notebook::isReadOnly(), this constraint does not affect the NotebookEntry objects that this Notebook contains. Thus, a Notebook that is not deletable may still have its NotebookEntry objects deleted (as long as the Notebook is not also read-only).

Return:

true if this Notebook is deletable, false otherwise.

Since:

BlackBerry 10.0.0

bool isReadOnly ()

Indicates whether this Notebook or its NotebookEntry objects can be edited.

Some system-created notebooks do not allow their contents (including their notebook entries) to be changed in any way. Any attempt to update this type of Notebook or its NotebookEntry objects by using NotebookService will result in that operation being rejected with an appropriate error code (see the individual NotebookService functions for details on which error code is returned). You should query this function to determine whether an operation is supported before attempting to invoke that operation, and UIs should query this function to determine whether to present such operations to the user.

A read-only Notebook does not allow the following operations to take place:
Return:

true if this Notebook is read-only, false otherwise.

Since:

BlackBerry 10.0.0

bool isValid ()

Indicates whether this Notebook is valid.

A default-constructed Notebook is considered invalid until at least one of its values is set. You should use this function to determine if a Notebook is valid before you use it. For example, if you call NotebookService::notebook() to retrieve a Notebook but you provide a non-existent ID, the Notebook object that is returned will be invalid.

Return:

true if this Notebook is valid, false otherwise.

Since:

BlackBerry 10.0.0

QString name ()

Retrieves the name of this Notebook.

Return:

The name of this Notebook.

Since:

BlackBerry 10.0.0

bool operator!= (

Inequality operator.

This operator indicates whether the provided Notebook contains a different name or different attributes than this Notebook. The purpose of this operator is to compare only the user-editable contents of the two Notebook objects; other fields, such as ID and type, are not considered.

To determine whether two Notebook objects represent different notebooks in the database, you should do an inequality comparison on the IDs of the two Notebook objects, rather than on the Notebook objects themselves.

Parameters
other

The Notebook to compare to this one for inequality of name or attributes.

Return:

true if the provided Notebook has a different name or different attributes than this Notebook, false otherwise.

Since:

BlackBerry 10.0.0

Notebook & operator= (

Assignment operator.

This operator copies all values from the provided Notebook into this Notebook.

Parameters
other

The Notebook from which to copy all values.

Return:

A reference to this Notebook.

Since:

BlackBerry 10.0.0

bool operator== (

Equality operator.

This operator indicates whether the provided Notebook contains the same name and attributes as this Notebook. The purpose of this operator is to compare only the user-editable contents of the two Notebook objects; other fields, such as ID and type, are not considered.

To determine whether two Notebook objects represent the same notebook in the database, you should do an equality comparison on the IDs of the two Notebook objects, rather than on the Notebook objects themselves.

Parameters
other

The Notebook to compare to this one for equality of name and attributes.

Return:

true if the provided Notebook has the same name and attributes as this Notebook, false otherwise.

Since:

BlackBerry 10.0.0

void resetAttribute (

Resets the value of the attribute with the provided key to a null QString.

Parameters
key

The key of the attribute whose value is to be reset.

Since:

BlackBerry 10.0.0

void setAttribute (

Sets an attribute to the given value for this key for this Notebook.

You can set your own attributes on a Notebook and these attributes will be persisted for later use.

Parameters
key

The key of the attribute.

value

The value of the attribute.

Since:

BlackBerry 10.0.0

void setDomain (

Sets the notebook domain that this Notebook will support.

Parameters
domain

the new domain for this Notebook.

This can only be set when creating a new Notebook. Any attempts to edit this will silently fail.
Since:

BlackBerry 10.3.0

void setName (

Sets the name for this Notebook.

Parameters
name

The new name for this Notebook.

Since:

BlackBerry 10.0.0

Type type ()

Retrieves the type of this Notebook.

The types of notebooks are described in the Notebook::Type enumeration.

Return:

The type of this Notebook.

Since:

BlackBerry 10.0.0

Last modified: 2014-09-29



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

comments powered by Disqus