RenderFence

Since: BlackBerry 10.0.0

#include <bb/cascades/RenderFence>

Provides a way to get notified when current changes to the scene associated with particular window have been rendered.

Fence can be used to ensure the window content has been updated before the application issues "cardReady" reply to InvokeManager for example, or to find out when the set scene has been rendered.

When created the fence is in RenderFenceState::Created state. From this state it can change to the following end states:
  • RenderFenceState::NotReached : fence becomes NotReached when it was raised but hasn't yet been Reached, Aborted or TimedOut

  • RenderFenceState::Reached : fence becomes Reached at some point after the changes made to the scene after it was Raised are rendered and presented. The timing of this state change is not guaranteed, the only thing that is guaranteed that it the fence will change the state at some point after the rendering has completed.

  • RenderFenceState::Aborted : if the raised property was set to false while in NotReached state, or if for some reason the fence can not be reached, for example rendering has been halted due to window or application state change such as window being minimized, card pooled and so on.

  • RenderFenceState::TimedOut : when the fence was not reached or aborted within 3 seconds.

By default the fence is created for the main window ( The render fence must be raised before it can be reached, which can be done by setting the raised property to true. The fence can be re-used by setting the raised property to true again after it has reached any of the ending states (RenderFenceState::Reached, RenderFenceState::Aborted, RenderFenceState::TimedOut).

The fence can also be explicitly aborted by setting the raised property to false.

Warning!
Due to backwards compatibility reasons there is one exception when the fence doesn't have to be explicitly raised after creation: if it is created using builder and the builder has been assigned to a variable. In this case the fence will be raised automatically (raised property will be set to true):
// Created using constructor, not raised.
RenderFence *fence = new RenderFence();
// Created with builder but not assigned or explicitly raised(), not raised.
RenderFence::create();

// Created with builder and assigned: the following fence WILL be raised.
RenderFence *raisedFence = RenderFence::create();

// To prevent assigned fence from being raised set raised to @c false.
RenderFence *raisedFence = RenderFence::create().raised(false);
An example of creating a render fence and connecting application's slots to its signals. The fence will change its state when the scene has been rendered and presented, and it will automatically delete itself once any of the signals are emitted:
myScene = //... Create the scene.
Application::instance()->setScene(myScene);

RenderFence::create()
    .parent(myApplication)
    .onReached(myApplication, SLOT(handleReached()))
    .onTimedOut(myApplication, SLOT(handleTimedOut()))
    .onAborted(myApplication, SLOT(handleAborted()))
    .autoDeleted()
    .raised(true);
An example of using the fence from QML:
Button {
    text: "Change Button Opacity"
    enabled: !fence.raised
    onClicked: {
        opacity = opacity * 0.9
        fence.raised = true
    }
    attachedObjects: [
        RenderFence {
            id: fence
        }
    ]
}


Overview

Inheritance

bb::cascades::BaseObject
bb::cascades::RenderFence

QML properties

raised: bool
state: bb::cascades::RenderFenceState::Type [read-only]
objectName: QStringInherited
parent: QObject [read-only]Inherited

Properties Index

boolraised
bb::cascades::RenderFenceState::Typestate [read-only]
QStringobjectNameInherited
QObjectparent [read-only]Inherited

Public Functions Index

RenderFence (QObject *parent=0)
virtual ~RenderFence ()
boolisRaised () const
Q_SLOT voidresetRaised ()
Q_SLOT voidsetRaised (bool raised)
bb::cascades::RenderFenceState::Typestate () const
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

voidaborted ()
voidfailedToReach ()
voidraisedChanged (bool raised)
voidreached ()
voidstateChanged (bb::cascades::RenderFenceState::Type newState)
voidtimedOut ()
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Properties

bool raised

Property indicating whether the fence is raised or not.

Note:
For compatibility reasons, one exception is that the property will be set to true if render fence is created using builder and assigned to a variable without setting raised property:
// The created fence is raised.
RenderFence *raisedFence = RenderFence::create();
// To create a non-raised fence specify the raised property in the builder:
RenderFence *notRaisedFence = RenderFence::create().raised(false);
Since:

BlackBerry 10.0.0

bb::cascades::RenderFenceState::Type state[read-only]

Property indicating the state of the RenderFence.

A stateChanged() signal is emitted when the value of this property changes.

In addition a reached() signal is emitted when RenderFence changes its state to RenderFenceState::Reached, aborted() signal is emitted when state is RenderFenceState::Aborted, and timedOut() when state is RenderFenceState::TimedOut.

The default value is RenderFenceState::Created.

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

Public Functions

RenderFence (

Construct a RenderFence instance.

If RenderFence created with the constructor the application must use raise() method to raise the fence.

Since:

BlackBerry 10.0.0

virtual~RenderFence ()

Destructor.

Since:

BlackBerry 10.0.0

bool isRaised ()

Returns current value of raised property.

Return:

true if the fence is raised, and false otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT void resetRaised ()

Resets the value of raised property to the default value false.

Since:

BlackBerry 10.0.0

Q_SLOT void setRaised (
  • boolraised)

Changes the value of raised property.

If set to true the fence becomes raised; state changes to RenderFenceState::NotReached.

If set to false the state changes to RenderFenceState::Aborted.

A raisedChanged() signal is emitted when this property changes. In addition stateChanged() may be emitted.

Parameters
raised

if true the fence is raised, otherwise it becomes not raised.

Since:

BlackBerry 10.0.0

bb::cascades::RenderFenceState::Type state ()

Returns the state of the render fence.

Return:

The state of the render fence.

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 a RenderFence.

Using the builder to create a RenderFence:
RenderFence* renderFence = RenderFence::create();
Return:

A builder used for constructing a RenderFence.

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

Emitted when the RenderFence state becomes RenderFenceState::Aborted.

Since:

BlackBerry 10.0.0

void failedToReach ()

Emitted when the RenderFence state becomes either RenderFenceState::TimedOut or RenderFenceState::Aborted.

This is a convenience signal which can be used to connect single slot to handle both non-reach states.

It is emitted in addition to aborted() and timedOut().

Since:

BlackBerry 10.0.0

void raisedChanged (
  • boolraised)

Emitted when the raised property changes.

Parameters
raised

the new value of raised property. If it is true the fence has been raised (corresponds to RenderFenceState::NotReached), if it is false the fence is not currently raised.

Since:

BlackBerry 10.0.0

void reached ()

Emitted when the renderfence state becomes RenderFenceState::Reached.

Since:

BlackBerry 10.0.0

void stateChanged (

Emitted when the state of the RenderFence instance changes.

Note:

Due to a work around for a Qt Core issue with accessing enums from QML the argument of this signal doesn't follow naming convention for signals in which the signal arguments are typically named to match the associated property's name. Use the object's property to access current property value instead of the signal argument to avoid runtime errors (i.e. use state instead of newState).

Parameters
newState

the new state of the RenderFence

Since:

BlackBerry 10.0.0

void timedOut ()

Emitted when the RenderFence state becomes RenderFenceState::TimedOut.

Since:

BlackBerry 10.0.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-06-24



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

comments powered by Disqus