MenuManager

#include <bb/system/MenuManager>

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

An interface for populating a menu of invokable items.

The menu service provides common context-aware logic for building menus. It can construct menus based on a specified type of data. The menu service uses the data, its type, and the context in which the data is being acted on to build a menu and populate it with information to be displayed and with the actions to be performed when an item in the menu is selected.

To build a menu of invokable items, create an instance of the MenuManager class, populate the required parameters using the setter methods, and call populateMenu() to send the request.

The menu service populates menus based on the context of the data being acted upon. The data being acted upon can be specified using a combination of URI, MIME type, and the data being acted upon. Typically, the data will be specified using one of these combinations:

  • Specify the URI to the data. The type of the data will be inferred by the menu service.

  • Specify the URI to the data and the MIME type of the data to which the URI refers.

  • Specify the data and its MIME type.

If all three properties are specified, then the MIME type shall be assumed to be the MIME type of the data referenced by the URI.

Connect to the finished() signal to receive a notification that the menu service has completed the request. Call error() to check that the request was successful; if so, retrieve the populated menu using menu().

Here's an example of how to send a request, receive the response, and read the menu data.

// Populate the query parameters.
bb::system::MenuManager *_menuManager = new MenuManager;
_menuManager->setUri(QUrl("file://path/to/file"));
_menuManager->setTargetTypes(InvokeTarget::Application);

// Connect to the finished() signal.
connect(_menuManager, SIGNAL(finished()), this, SLOT(onFinished()));

// Send the request to have the menu populated.
if (_menuManager->populateMenu() != true) {
    // Handle the error.
}

// Define a slot to receive the finished() signal.
Q_SLOT void onFinished()
{
    // Check for errors.
    if (_menuManager->error() != MenuManagerError::None) {
        // Handle the error.
    } else {
        // The menu was populated. Retrieve the data.
        bb::system::Menu = _menuManager->menu();
    }
}

Since:

BlackBerry 10.0.0

Public Functions Index

MenuManager (QObject *parent=0)
virtual ~MenuManager ()
voidsetAction (const QString &action)
voidsetMimeType (const QString &mimeType)
voidsetUri (QUrl uri)
voidsetFileTransferMode (bb::system::FileTransferMode::Type fileTransferMode)
voidsetData (const QByteArray &data)
voidsetMetadata (const QVariantMap &metadata)
voidsetTargetTypes (InvokeTarget::Types types)
voidsetPerimeter (SecurityPerimeter::Type perimeter)
QStringaction () const
QStringmimeType () const
QUrluri () const
bb::system::FileTransferMode::TypefileTransferMode () const
QByteArraydata () const
QVariantMapmetadata () const
InvokeTarget::TypestargetTypes () const
SecurityPerimeter::Typeperimeter () const
boolpopulateMenu ()
Menumenu () const
MenuManagerError::Typeerror () const
boolisFinished () const

Signals Index

voidfinished ()

Public Functions

MenuManager (

Creates a new MenuManager object.

Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.
Since:

BlackBerry 10.0.0

virtual~MenuManager ()

Destructor.

Since:

BlackBerry 10.0.0

void setAction (

Sets the action to be used to filter the invoke target results.

If no action is provided, all actions will be considered.

Required: NO

Parameters
action

The action to set.
Since:

BlackBerry 10.0.0

void setMimeType (

Sets the MIME type of the data to be acted on.

If a URI is specified, the MIME type is not required and the menu service will infer the type of data being acted upon. If a URI is not specified, then the MIME type is required.

Required: YES, if the URI is not set; NO, if a URI is set.

Parameters
mimeType

The MIME type of the data to be acted on.
Since:

BlackBerry 10.0.0

void setUri (

Sets the URI of the data for which the menu applies.

Note:

For URIs to local files, consider using QUrl::fromLocalFile() to construct a QUrl instance.

Parameters
uri

The URI of the data.
Since:

BlackBerry 10.0.0

void setFileTransferMode (

Sets the file transfer mode of the data for which the menu applies.

The file transfer mode will be applied if the scheme of the URI is "file://" and the path references a file that is not in the shared area.

Parameters
fileTransferMode

The file transfer mode of the data. See bb::system::FileTransferMode for the list of possible transfer modes.
Since:

BlackBerry 10.0.0

void setData (

Sets the data to be acted upon.

Parameters
data

The data to be acted upon.
Since:

BlackBerry 10.0.0

void setMetadata (

Sets the metadata associated with the invocation.

Metadata is optional and can be included to pass additional information to the target. It will be encoded as a JSON object and sent to the target.

Parameters
metadata

The metadata to be associated with the invocation.
Since:

BlackBerry 10.0.0

void setTargetTypes (
  • InvokeTarget::Typestypes)

Sets the target types, which indicate the types of targets to consider when building the menu.

Required: NO

Parameters
types

The target types. See bb::system::InvokeTarget::Type for the list of individual target types.
Note:

The menu service does not construct menus that contain viewer targets. Therefore, bb::system::InvokeTarget::Viewer is not a valid value. The menu service will reject queries that contain bb::system::InvokeTarget::Viewer as a target type.

Since:

BlackBerry 10.0.0

void setPerimeter (

Sets the perimeter in which the selected action is to be invoked.

Required: NO

Parameters
perimeter

The perimeter in which the selected action is to be invoked. See bb::system::SecurityPerimeter for the list of perimeters.
Since:

BlackBerry 10.0.0

QString action ()

Returns the action.

Return:

The action.

Since:

BlackBerry 10.0.0

QString mimeType ()

Returns the MIME type of the data to be acted upon.

Return:

The MIME type of the data.

Since:

BlackBerry 10.0.0

QUrl uri ()

Returns the URI of the data for which the menu applies.

Return:

The URI of the data.

Since:

BlackBerry 10.0.0

bb::system::FileTransferMode::Type fileTransferMode ()

Returns the file transfer mode of the data for which the menu applies.

The file transfer mode will be applied if the scheme of the URI is "file://" and the path references a file that is not in the shared area.

Return:

The file transfer mode of the data. See bb::system::FileTransferMode for the list of file transfer modes.

Since:

BlackBerry 10.0.0

QByteArray data ()

Returns the data that is to be acted on.

Return:

The data to be acted on.

Since:

BlackBerry 10.0.0

QVariantMap metadata ()

Returns the metadata associated with the invocation.

Metadata is optional and can be included to pass additional information to the target. It will be encoded as a JSON object and sent to the target.

Return:

The metadata.

Since:

BlackBerry 10.0.0

InvokeTarget::Types targetTypes ()

Returns the target types.

Return:

The target types. See bb::system::InvokeTarget::Type for the list of individual target types.

Since:

BlackBerry 10.0.0

SecurityPerimeter::Type perimeter ()

Returns the perimeter in which the selected action is to be invoked.

Return:

The perimeter in which the action will be invoked.

Since:

BlackBerry 10.0.0

bool populateMenu ()

Sends a request to the menu service to populate a menu of invokable items based on the properties set as criteria.

It is recommended that the client only make one request at a time on the same MenuManager instance. If a new request is made before receiving a reply from a previous request, the end result can be indeterminate if the state of the MenuManager instance changes. This can happen because replies may be received in a different order than requests were made.

Return:

true if the request was successful, false otherwise.

Since:

BlackBerry 10.0.0

Menu menu ()

Returns the populated list of menu items.

The returned menu is not valid until the finished() signal has been emitted, and when error() returns MenuManagerError::None.

Return:

The populated list of menu items, or an empty list if the menu has not been populated or if the request was unsuccessful.

Since:

BlackBerry 10.0.0

MenuManagerError::Type error ()

Returns the error code from the menu service.

The error code is not valid until the finished() signal has been emitted.

Return:

The error code from the menu service. See bb::system::MenuManagerError for the list of possible errors.

Since:

BlackBerry 10.0.0

bool isFinished ()

Checks whether a reply from the menu service has been received.

If this method returns false, the values returned by the menu() and error() methods are not valid. If this method returns true, the value returned by error() gives the status of the last request. If the request was successful, menu() will return a valid, populated menu obtained from the menu service.

Return:

true if a reply from the menu service has been received and this object is valid, false otherwise.

Since:

BlackBerry 10.0.0

Signals

void finished ()

Emitted when this object becomes valid.

When this signal is received, the value returned by error() is valid. If the request was successful, menu() will return a valid, populated menu obtained from the menu service.

Since:

BlackBerry 10.0.0