InputRouteProperties

Since: BlackBerry 10.1.0

#include <bb/cascades/InputRouteProperties>

Optional group of properties that can be set on controls to define their role in the propagation of input events and influence the default routing logic.

This is typically used to indicate that the control is the default target of some type of input event when a target cannot be determined by the another propagation mechanism. E.g. if there is no focused control, setting inputRoute.primaryKeyTarget to true on a control will make it the target of key events.


Overview

Inheritance

bb::cascades::BaseObject
bb::cascades::UIObject
bb::cascades::InputRouteProperties

QML properties

keysIgnoreFocusInSubtree: bool
primaryKeyTarget: bool
attachedObjects: QDeclarativeListProperty< QObject > [read-only]Inherited
objectName: QStringInherited
parent: QObject [read-only]Inherited
ui: bb::cascades::UIConfig [read-only]Inherited

Properties Index

boolkeysIgnoreFocusInSubtree
boolprimaryKeyTarget
QDeclarativeListProperty< QObject >attachedObjects [read-only]Inherited
QStringobjectNameInherited
QObjectparent [read-only]Inherited
bb::cascades::UIConfigui [read-only]Inherited

Public Functions Index

InputRouteProperties (UIObject *parent=0)
virtual ~InputRouteProperties ()
boolisPrimaryKeyTarget () const
boolkeysIgnoreFocusInSubtree () const
Q_SLOT voidresetKeysIgnoreFocusInSubtree ()
Q_SLOT voidresetPrimaryKeyTarget ()
Q_SLOT voidsetKeysIgnoreFocusInSubtree (bool keysIgnoreFocusInSubtree)
Q_SLOT voidsetPrimaryKeyTarget (bool primaryKeyTarget)
virtual boolevent (QEvent *event)Inherited
voidsetObjectName (const QString &name)Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited
Q_INVOKABLE bb::cascades::UIConfig *ui () const Inherited

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited
virtual voidconnectNotify (const char *signal)Inherited
virtual voiddisconnectNotify (const char *signal)Inherited

Signals Index

voidkeysIgnoreFocusInSubtreeChanged (bool keysIgnoreFocusInSubtree)
voidprimaryKeyTargetChanged (bool primaryKeyTarget)
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Properties

bool keysIgnoreFocusInSubtree

If the focused control is this or a control somewhere in this subtree, deliever events as if nothing had focus.

Note:

setting this property will not block key events from being delivered to a primary key target in subtree.

The default value for this property is false.
Since:

BlackBerry 10.3.1

bool primaryKeyTarget

Indicates that the owner of these properties should be treated as primary key target.

This property is read by the event system when a key event is about to be propagated and there is no focused control. The event system scans the content of the current page, and when a page or control with this property set to true is found, it will be used as the target for the key event. The event then bubbles up to the root according to standard key event propagation rules.

The intent is to enable the developer to set a primary key target per page. If the primary key target needs to change for some reason, it is up to the developer to reset and set this property where needed. The scan will always pick the first occuring primary key target, in a pre-order depth first search from the page (meaning parents have precedence over children).

Note:

Focus set explicitly with Control::requestFocus() overrides the effect of this property. I.e. once focus has been set on a control, this property has no effect.

,

There is no visual hint to indicate which control or page is the effective main key target. It can be confusing for a user if it changes within the same screen.

The default value for this property is false.
QML usage:
Container {
    inputRoute.primaryKeyTarget: true

    Label {
        id: myLabel
        text: "Press a"
    }

    shortcuts: [
        Shortcut {
            key: "a"
            onTriggered: {
                myLabel.text = "Shortcut triggered!"
            }
        }
    ]
}
C++ usage:
Container *pContainer = new Container();
pContainer->inputRoute()->setPrimaryKeyTarget(true);
// Shortcuts on pContainer can now trigger.
C++ usage (with builder):
Container *pContainer = Container::create()
    .primaryKeyTarget(true)
    .add(Label::create()
            .text("My container will get key events!"));
Since:

BlackBerry 10.1.0

QDeclarativeListProperty< QObject > attachedObjectsInherited[read-only]

A hierarchical list of the UIObject's attached objects.

Since:

BlackBerry 10.0.0

QString objectNameInherited

This property is overridden from QObject.

See also:

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

bb::cascades::UIConfig uiInherited[read-only]

An object that gives access to unit conversion routines.

QML use:
        // Size using design units
        Container {
            preferredWidth: ui.du(12)
            preferredHeight: ui.du(5)
        }

        // Size using design units, snap to whole pixels
        Container {
            preferredWidth: ui.sdu(13.5)
            preferredHeight: ui.sdu(7.5)
        }

        // Size using absolute pixel values
        Container {
            preferredWidth: ui.px(150)
            preferredHeight: ui.px(50)
        }
C++ use:
Container *container1 = Container::create().background(Color::Red);
UIConfig *ui = container1->ui();
container1->setPreferredWidth(ui->du(12));
container1->setPreferredHeight(ui->du(5));

Container *container2 = Container::create().background(Color::Green);
container2->setPreferredWidth(ui->sdu(13.5));
container2->setPreferredHeight(ui->sdu(7.5));

Container *container3 = Container::create().background(Color::Blue);
container3->setPreferredWidth(ui->px(150));
container3->setPreferredHeight(ui->sdu(50));
Since:

Blackberry 10.3.0

Public Functions

InputRouteProperties (

Constructs an InputRouteProperties object with a parent UIObject.

The ownership of the InputRouteProperties object is transferred to the parent, if a parent is specified.

Parameters
parent

The parent UIObject, or 0. This parameter is optional. The default is 0 if you don't specify a parent.

Since:

BlackBerry 10.1.0

virtual~InputRouteProperties ()

Destructor.

bool isPrimaryKeyTarget ()

Returns the primaryKeyTarget state of the control.

Return:

true if the control is set to be primary key target, false otherwise.

Since:

BlackBerry 10.1.0

bool keysIgnoreFocusInSubtree ()

Returns the keysIgnoreFocusInSubtree state of the control.

Return:

true if the control is set to be key blocker, false otherwise.

Since:

BlackBerry 10.3.1

Q_SLOT void resetKeysIgnoreFocusInSubtree ()

Resets the keysIgnoreFocusInSubtree state of the control to false.

Since:

BlackBerry 10.3.1

Q_SLOT void resetPrimaryKeyTarget ()

Resets the primaryKeyTarget state of the control to false.

Since:

BlackBerry 10.1.0

Q_SLOT void setKeysIgnoreFocusInSubtree (
  • boolkeysIgnoreFocusInSubtree)

Sets the keysIgnoreFocusInSubtree state of the control.

Parameters
keysIgnoreFocusInSubtree

If true the control is a key blocker and if false the control is not a key blocker.

Since:

BlackBerry 10.3.1

Q_SLOT void setPrimaryKeyTarget (
  • boolprimaryKeyTarget)

Sets the primaryKeyTarget state of the control.

Parameters
primaryKeyTarget

If true the control is a primary key target and if false the control is not a primary key target.

Since:

BlackBerry 10.1.0

virtual bool event (Inherited

Overloaded to implement the event mechanism in Cascades.

Warning!

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
event

The received event.

Return:

True if the received event was recognized and processed, false otherwise.

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

Q_INVOKABLE bb::cascades::UIConfig * ui ()Inherited

Returns the UIConfig for this ui object.

The UIConfig can be used to perform unit conversions from design units (du) and snapped design units (sdu) to pixels.

Ownership remains with Cascades.

C++ use:
Container *container1 = Container::create().background(Color::Red);
UIConfig *ui = container1->ui();
container1->setPreferredWidth(ui->du(12));
container1->setPreferredHeight(ui->du(5));

Container *container2 = Container::create().background(Color::Green);
container2->setPreferredWidth(ui->sdu(13.5));
container2->setPreferredHeight(ui->sdu(7.5));

Container *container3 = Container::create().background(Color::Blue);
container3->setPreferredWidth(ui->px(150));
container3->setPreferredHeight(ui->sdu(50));
Return:

The UIConfig for this ui object.

Since:

BlackBerry 10.3.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

virtual void connectNotify (
  • const char *signal)
Inherited

Overloaded to implement the event mechanism in Cascades.

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
signal

The connected signal.

Since:

BlackBerry 10.0.0

virtual void disconnectNotify (
  • const char *signal)
Inherited

Overloaded to implement the event mechanism in Cascades.

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
signal

The disconnected signal.

Since:

BlackBerry 10.0.0

Signals

void keysIgnoreFocusInSubtreeChanged (
  • boolkeysIgnoreFocusInSubtree)

Emitted when the keysIgnoreFocusInSubtree property changes.

Parameters
keysIgnoreFocusInSubtree

The new value of keysIgnoreFocusInSubtree.

Since:

BlackBerry 10.3.1

void primaryKeyTargetChanged (
  • boolprimaryKeyTarget)

Emitted when the primaryKeyTarget property changes.

Parameters
primaryKeyTarget

The new value of primaryKeyTarget.

Since:

BlackBerry 10.1.0

void creationCompleted ()Inherited

Emitted 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 indicates 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 also:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

Since:

BlackBerry 10.0.0

Last modified: 2014-09-30



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

comments powered by Disqus