InvokeHandler

#include <bb/cascades/InvokeHandler>

Communicates with the caller when an action item is ready to invoke the target.

This InvokeHandler is delegated the task of communication with the caller from an InvokeActionItem. The communication is initiated when the signal InvokeHandler::invoking() is triggered by the delegator. Then InvokeHandler waits for the caller to call either InvokeHandler::confirm() or InvokeHandler::cancel(). The InvokeHandler returns back the delegator. If a new signal InvokeHandler::invoking() is triggered by this InvokeHandler while waiting for an answer from the caller, the previous session is ignored.

The following sample code shows how to use InvokeHandler in collaboration with an InvokeActionItem in QML:

ImageView {
  attachedObjects: [
    Dialog {
      id: myDialog
      onClosed: {
        if (isOk()) {
          myHandler.confirm()
        }
      }
      onCancel: {
        if (isOk()) {
          myHandler.cancel()
        }
      }
    }
  ]
  contextActions: [
    ActionSet {
      InvokeActionItem {
        handler : InvokeHandler {
          onInvoking: {
            myDialog.open()
          }
        }
      }
    }
  ]
}

This InvokeHandler can be shared among several invoke action items too. In this case, it need to be placed in an attached object of a common parent. The following sample code explains this:

  ImageView {
    attachedObjects: [
      InvokeHandler {
        id: myHandler
        onInvoking: {
          myDialog.open()
        }
      },
      Dialog {
        id: myDialog
        onClosed: {
          if (isOk()) {
            myHandler.confirm()
          }
        }
        onCancel: {
          if (isOk()) {
            myHandler.cancel()
          }
        }
      }
   ]
   contextActions: [
     ActionSet {
       InvokeActionItem {
         query {
           // whatever
         }
         handler: myHandler
       }
     }
   ]
*}

In C++ using a handler may look like this:

  InvokeHandler hand;
  InvokeActionItem item;
  Label* notify;
 
  void onInvokingHandler() {
      // Show dialog and set connect button clicked slots
      // In this case onConfirmedClicked() and onCancelledClicked()
  }
 
  void onConfirmedClicked() {
      item.handler()->confirm();
  }
 
  void onCancelledClicked() {
      item.handler()->cancel();
  }
 
  void onHandlerChangedHandler(const bb::cascades::InvokeHandler* hand) {
      notify.setText("Handler has been updated!");
  }
 
  hand = invokeHandler::create()
      .onInvoking(this, SLOT(onInvokingHandler()));
 
  item = InvokeActionItem::create(
          InvokeQuery::create()
              .mimeType("image/png")
              .parent(this))
          .title("Comfirm invocation")
          .handler(hand)
          .onHandlerChanged(this, SLOT(onHandlerChangedHandler(const bb::cascades::InvokeHandler*)));
 
  notify = Label::create();
*

Since:

BlackBerry 10.0.0

Inheritance

bb::cascades::BaseObject
bb::cascades::InvokeHandler

QML properties

Only has inherited QML properties

objectName: QStringInherited
parent: QObject [read-only]Inherited

QML signals

onInvoking: {}
onCreationCompletedInherited: {}
onObjectNameChangedInherited: {}

Properties Index

Only has inherited properties

QStringobjectNameInherited
QObjectparent [read-only]Inherited

Public Functions Index

~InvokeHandler ()
Q_SLOT voidconfirm ()
Q_SLOT voidcancel ()
voidsetObjectName (const QString &name)Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited

Static Public Functions Index

Buildercreate ()

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited

Signals Index

voidinvoking ()
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Properties

(Only has inherited properties)

QString objectNameInherited

This property is overridden from QObject.

As the objectName property is overridden from the QObject class, this signal will not be emitted if setObjectName() function is called directly on QObject.

The default value of this property is QString::null.

See:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parentInherited[read-only]

A read-only property that represents this object's parent.

The parent of an object is specified using QObject::setParent(QObject*). The purpose of the property is to expose the object's parent to QML.

This property is read-only to prevent modifications from QML, where typically the parent is declaratively set. In C++ code, the parent can be explicitly set using QObject::setParent(QObject*), or implicitly set by adding it to a visual container.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

Public Functions

~InvokeHandler ()

Destructor.

Q_SLOT void confirm ()

Used by the caller to confirm invocation.

The caller confirms a previously intercepted signal InvokeHandler::invoking() from this InvokeHandler that it wants to continue invoking the target.

Since:

BlackBerry 10.0.0

Q_SLOT void cancel ()

Used by the caller to cancel invocation.

The caller answers a previously intercepted signal InvokeHandler::invoking() from the handler that it wants to cancel the invocation session.

Since:

BlackBerry 10.0.0

void setObjectName (Inherited

Sets the objectName property.

Parameters
name

The new name for the object.
Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()Inherited

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Static Public Functions

Builder create ()

Creates and returns a builder for constructing an InvokeHandler.

Usage: 
InvokeHandler* hand(InvokeHandler::create());
Return:

A builder used for constructing an InvokeHandler.

Since:

BlackBerry 10.0.0

Protected Functions

(Only has inherited protected functions)

BaseObject (Inherited

Constructs an instance of BaseObject's subclass.

Parameters
parent

An optional parent, defaults to 0.
Since:

BlackBerry 10.0.0

Signals

void invoking ()

Emitted by the invoke action item when it is ready to invoke the target.

Since:

BlackBerry 10.0.0

void creationCompleted ()Inherited

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node, or when an object is being constructed using its builder class.

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node (only after the root component that caused this instantiation has completed construction), or when the object is being constructed from its builder class. This signal is emitted to indicate that the construction and initialization of the object has been completed, the properties are initialized, and any QML binding values have been assigned to the object.

This signal is not emitted when the object is constructed from C++ using the constructor. If the object is constructed using its builder class, the signal is emitted when the the builder class returns the fully constructed object.

This signal can be used when there is an activity that needs to be performed, such as a property state integrity verification after the object is instantiated from a QML document or a builder, but before control is returned to the application.

See:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

See:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0