NavigationPane

Since: BlackBerry 10.0.0

#include <bb/cascades/NavigationPane>

A class that is used for stack-like navigation between Page objects.

The NavigationPane keeps track of a stack of Page objects that can be pushed and popped on the stack. Only the topmost page on the stack is displayed to the user. The push() function adds a new page on the top of the navigation stack, displaying it while hiding the old page. The pop() function hides the page currently on the top of the stack, removing it from the navigation stack and displaying the previous page again.

The following example creates a NavigationPane and adds a page. A second page is created and added to the NavigationPane when nextAction is triggered. The second page has a custom back button set through the NavigationPaneProperties class. The NavigationPaneProperties class handles properties set to the NavigationPane in order to customize it.

The default back button will have a standard back icon and the title "Back".

This is how the back button will look like by default.

Here's an example of how to use NavigationPane in QML:

 // navigationpane.qml
 
 NavigationPane {
     id: navigationPane
     Page {
         Container {
             Label { 
                 text: "First page" 
             }
         }

         actions: [
             ActionItem {
                 title: "Next page"
                 ActionBar.placement: ActionBarPlacement.OnBar
                 onTriggered: {
                     var page = pageDefinition.createObject();
                     navigationPane.push(page);
                 }

                 attachedObjects: ComponentDefinition {
                     id: pageDefinition;
                     source: "secondpage.qml"
                 }
             }
         ]
     }
     onPopTransitionEnded: { page.destroy(); }
 }

 // secondpage.qml

 Page {
     Container {
         Label { 
             text: "Second page" 
         }
     }
     paneProperties: NavigationPaneProperties {
         backButton: ActionItem {
             title: "Previous page"
             imageSource: "asset:///back.png"
             onTriggered: { navigationPane.pop(); }
         }
     }
 }

And here's how to do the same using C++:

 NavigationPane* navigationPane;

 void initializeNavigationPane()
 {
     ActionItem* nextAction = ActionItem::create()
         .title("Next page")
         .onTriggered(this, SLOT(pushPage()));

     navigationPane = NavigationPane::create();
     QObject::connect(navigationPane, SIGNAL(popTransitionEnded(bb::cascades::Page*)), 
         this, SLOT(popFinished(bb::cascades::Page*)));

     navigationPane->push(Page::create()
         .content(Label::create("First page"))
         .addAction(nextAction, ActionBarPlacement::OnBar));

     Application::instance()->setScene(navigationPane);
 }

 void popFinished(bb::cascades::Page* page)
 {
     delete page;
 }

 Q_SLOT void pushPage()
 {
     ActionItem* backAction = ActionItem::create()
         .title("Previous page")
         .imageSource(QUrl("asset:///back.png"))
         .onTriggered(navigationPane, SLOT(pop()));

     navigationPane->push(Page::create()
         .content(Label::create("Second page"))
         .paneProperties(NavigationPaneProperties::create()
             .backButton(backAction)));
 }

Overview

Inheritance

bb::cascades::BaseObject
	bb::cascades::UIObject
		bb::cascades::AbstractPane
			bb::cascades::NavigationPane

QML properties

backButtonsVisible	: bool
peekEnabled	: bool
top	: bb::cascades::Page [read-only]
accessibility	: bb::cascades::AbstractA11yObject [read-only]
attachedObjects	: QDeclarativeListProperty< QObject > [read-only]
keyListeners	: QDeclarativeListProperty [read-only]
builtInShortcutsEnabled	: bool
objectName	: QString
paneProperties	: bb::cascades::PaneProperties
parent	: QObject [read-only]
peekedAt	: bool [read-only]
ui	: bb::cascades::UIConfig [read-only]

QML signals

onBackButtonsVisibleChanged	: {}
onNavigateToTransitionEnded	: {}
onPeekEnabledChanged	: {}
onPopTransitionEnded	: {}
onPushTransitionEnded	: {}
onTopChanged	: {}
onBuiltInShortcutsEnabledChanged	: {}
onCreationCompleted	: {}
onObjectNameChanged	: {}
onPanePropertiesChanged	: {}
onPeekedAtChanged	: {}
onPeekEnded	: {}
onPeekStarted	: {}

Properties Index

bool	backButtonsVisible
bool	peekEnabled
bb::cascades::Page	top [read-only]
bb::cascades::AbstractA11yObject	accessibility [read-only]
QDeclarativeListProperty< QObject >	attachedObjects [read-only]
QDeclarativeListProperty	keyListeners [read-only]
bool	builtInShortcutsEnabled
QString	objectName
bb::cascades::PaneProperties	paneProperties
QObject	parent [read-only]
bool	peekedAt [read-only]
bb::cascades::UIConfig	ui [read-only]

Public Functions Index

	NavigationPane (QObject *parent=0)
virtual	~NavigationPane ()
Q_INVOKABLE bb::cascades::Page *	at (int index) const
bool	backButtonsVisible () const
Q_INVOKABLE int	count () const
Q_INVOKABLE int	indexOf (bb::cascades::Page *page) const
Q_INVOKABLE void	insert (int index, bb::cascades::Page *page)
bool	isPeekEnabled () const
Q_SLOT QVariantList	navigateTo (bb::cascades::Page *targetPage)
Q_INVOKABLE bb::cascades::Page *	pop ()
Q_INVOKABLE void	push (bb::cascades::Page *child)
Q_INVOKABLE bool	remove (bb::cascades::Page *page)
Q_SLOT void	resetBackButtonsVisible ()
Q_SLOT void	resetPeekEnabled ()
Q_SLOT void	setBackButtonsVisible (bool visible)
Q_SLOT void	setPeekEnabled (bool enabled)
bb::cascades::Page *	top () const
bb::cascades::AbstractA11yObject *	accessibility () const
Q_INVOKABLE void	addKeyListener (bb::cascades::KeyListener *keyListener)
Q_INVOKABLE void	addShortcut (bb::cascades::AbstractShortcut *shortcut)
Q_INVOKABLE bool	builtInShortcutsEnabled () const
Q_INVOKABLE void	disableAllShortcuts ()
Q_INVOKABLE void	enableAllShortcuts ()
virtual bool	event (QEvent *event)
bool	isPeekedAt () const
Q_INVOKABLE bb::cascades::KeyListener *	keyListenerAt (int index) const
Q_INVOKABLE int	keyListenerCount () const
bb::cascades::PaneProperties *	paneProperties () const
Q_INVOKABLE void	removeAllKeyListeners ()
Q_INVOKABLE void	removeAllShortcuts ()
Q_INVOKABLE bool	removeKeyListener (bb::cascades::KeyListener *keyListener)
Q_INVOKABLE bool	removeShortcut (bb::cascades::AbstractShortcut *shortcut)
Q_SLOT void	resetBuiltInShortcutsEnabled ()
Q_SLOT void	resetPaneProperties ()
Q_INVOKABLE void	setBuiltInShortcutEnabled (bb::cascades::SystemShortcuts::Type type, bool enabled)
Q_SLOT void	setBuiltInShortcutsEnabled (bool enabled)
void	setObjectName (const QString &name)
Q_SLOT void	setPaneProperties (bb::cascades::PaneProperties *paneProperties)
Q_INVOKABLE bb::cascades::AbstractShortcut *	shortcutAt (int index) const
Q_INVOKABLE int	shortcutCount () const
virtual Q_INVOKABLE QString	toDebugString () const
Q_INVOKABLE bb::cascades::UIConfig *	ui () const

Static Public Functions Index

Builder

create ()

Protected Functions Index

Only has inherited protected functions

	BaseObject (QObject *parent=0)
virtual void	connectNotify (const char *signal)
virtual void	disconnectNotify (const char *signal)

Signals Index

void	backButtonsVisibleChanged (bool visible)
void	navigateToTransitionEnded (QVariantList pages)
void	peekEnabledChanged (bool enabled)
void	popTransitionEnded (bb::cascades::Page *page)
void	pushTransitionEnded (bb::cascades::Page *page)
void	topChanged (bb::cascades::Page *page)
void	builtInShortcutsEnabledChanged (bool builtInShortcutsEnabled)
void	creationCompleted ()
void	objectNameChanged (const QString &objectName)
void	panePropertiesChanged (bb::cascades::PaneProperties *paneProperties)
void	peekedAtChanged (bool peekedAt)
void	peekEnded ()
void	peekStarted ()

Properties

bool backButtonsVisible

Indicates whether the back buttons should be visible on all pushed pages in this NavigationPane.

Since:

BlackBerry 10.0.0

bool peekEnabled

Indicates whether peeking from within the current Page should be enabled.

When enabled, dragging or swiping to the right inside the content of the Page will reveal the previous Page in the navigation stack.

This property only controls whether or not peeking is enabled within the content area of the Page. Peeking is always enabled on the Back button, even if this property is disabled.

The default value is true (enabled).

Since:

BlackBerry 10.0.0

bb::cascades::Page top[read-only]

The topmost page on the stack of this NavigationPane.

This is the page that is currently displayed.

Since:

BlackBerry 10.0.0

bb::cascades::AbstractA11yObject accessibility[read-only]

Defines this pane's accessibility object.

See also:

Control::accessibility

Since:

BlackBerry 10.2.0

QDeclarativeListProperty< QObject > attachedObjects[read-only]

A hierarchical list of the UIObject's attached objects.

Since:

BlackBerry 10.0.0

QDeclarativeListProperty keyListeners[read-only]

A list of shortcuts that can be triggered via user actions.

A list of key listeners attached to this abstract pane.

The order in which they are added will determine which shortcut will be triggered in case of an overlap. Predefined shortcuts take precedence over shortcuts defined via QString in case of a collision.

See also:

AbstractShortcut

Since:

BlackBerry 10.1.0

The order in which key listeners are added does not change their behavior.

See also:

KeyListener

Since:

BlackBerry 10.1.0

bool builtInShortcutsEnabled

Enables or disables all AbstractPane's core shortcuts.

This property is used when all AbstractPane's core shortcuts should be enabled or disabled.

Since:

BlackBerry 10.2.0

QString objectName

This property is overridden from QObject.

See also:

QObject::objectName().

Since:

BlackBerry 10.0.0

bb::cascades::PaneProperties paneProperties

The pane properties for this AbstractPane.

The paneProperties property specifies data that the parent AbstractPane may use. The type of pane properties of the child must match up with parent. For example, if you add a Page to a NavigationPane, you must use NavigationPaneProperties.

By default, the paneProperties of an AbstractPane is 0.

Since:

BlackBerry 10.0.0

QObject parent[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

bool peekedAt[read-only]

Indicates whether this AbstractPane is being "peeked" at.

If true, the pane is currently being revealed by peeking from a Sheet or a Page within a NavigationPane. By default, the value is false, indicating that the pane is not currently being peeked at.

If a NavigationPane is being peeked at, both the NavigationPane and its currently visible page will return true for the peekedAt property.

As a convenience, there are two signals available called peekStarted and peekEnded, which are emitted when a peek on the AbstractPane starts or ends.

The peekedAtChanged() signal is emitted when peekedAt changes.

Since:

BlackBerry 10.0.0

bb::cascades::UIConfig ui[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

NavigationPane (
QObject *parent)

Constructs a NavigationPane.

Creating a NavigationPane object:

 NavigationPane* navigationPane = new NavigationPane();
 navigationPane->push(new Page());

Since:

BlackBerry 10.0.0

virtual~NavigationPane ()

Destructor.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::Page * at (
intindex)

Returns a page at the specified index.

The index starts from the bottom of the stack, so the bottom page will have index 0. Once completed, ownership of the page remains with the NavigationPane.

Parameters
index	The index of the page.

Return:

The requested page if the index was valid, 0 otherwise.

Since:

BlackBerry 10.0.0

bool backButtonsVisible ()

Indicates whether back buttons are visible or not for this NavigationPane.

Return:

true if back buttons are visible, false otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE int count ()

Returns the number of pages in the navigation stack.

Return:

The number of pages in the navigation stack.

Since:

BlackBerry 10.0.0

Q_INVOKABLE int indexOf (
bb::cascades::Page *page)

Returns the index of a page.

The index starts from the bottom of the stack, so the bottom page will have index 0. If the page isn't in the navigation stack or the page is 0, -1 is returned.

Parameters
page	The page to get the index from.

Return:

The index of the specified page if the page is valid, -1 otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void insert (
intindex,
bb::cascades::Page *page )

Inserts a page at a specified index in the NavigationPane.

The page that is passed must not be 0 or it will be ignored. If the page is already present in the navigation stack, the operation will fail. This operation will not trigger a transition effect, even if the page is added to the top of the stack. If a transition effect is desired, use push() instead. The topChanged() signal will be emitted if the operation affects the top node.

Parameters
index	The index where the page will be placed. If the index < 0 the the page is inserted in the bottom. If the index > the number of pages in the navigation stack, it is added on top of the stack.
page	The page to be inserted, must not be 0.

Since:

BlackBerry 10.0.0

bool isPeekEnabled ()

Indicates whether peeking from within the content area of the current page is enabled.

Peeking is always enabled on the Back button, even if this property is disabled.

Return:

true if peeking is enabled, false otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT QVariantList navigateTo (
bb::cascades::Page *targetPage)

Navigates to the specified page if it is present in the stack of this NavigationPane.

If the page is present in the stack, this function emits the topChanged() signal immediately. Any pages above the one navigated to in the stack will be removed from the stack with a single transition animation.

When the the transition is finished, this function emits the navigateToTransitionEnded() signal The NavigationPane keeps the ownership of the pages. The pages can be safely deleted at any time after the call to navigateTo().

If a given page happens to be deleted before the navigateToTransitionEnded() signal has been emitted, that page will be excluded from the list of removed pages that are passed as input parameter to the navigateToTransitionEnded() signal.

The removed pages can not be pushed to another control (e.g. another NavigationPane) until after the navigateToTransitionEnded() signal has been received. Furthermore, in order to be able to push a removed Page to another control after the navigateToTransitionEnded() signal has been received, its parent must also be set to zero.

Return:

A QVariantList containing the pages that were removed from the NavigationPane stack. If the navigation stack was empty, or the targetPage was not present in the stack, an empty list is returned.

See also:

navigateToTransitionEnded(), push()

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::Page * pop ()

Pops the top page from the stack of this NavigationPane.

If the stack is not empty, this function emits the topChanged() signal immediately. When the the transition is finished, the popTransitionEnded() signal is also emitted.

The NavigationPane keeps the ownership of the Page. The Page can be safely deleted at any time after the call to pop(). If the Page happens to be deleted before the popTransitionEnded() signal has been emitted, that signal will have the parameter for the popped Page set to 0.

The popped Page can not be pushed to another control (e.g. another NavigationPane) until after the popTransitionEnded() signal has been received. Furthermore, in order to be able to push the popped Page to another control after the popTransitionEnded() signal has been received, its parent must also be set to zero.

Return:

The page that was popped from the navigation stack. If the navigation stack was empty, 0 is returned.

See also:

popTransitionEnded(), push()

Since:

BlackBerry 10.0.0

Q_INVOKABLE void push (
bb::cascades::Page *child)

Pushes a Page onto the stack of this NavigationPane.

The pushed page is placed on the top of the navigation stack, and is displayed to the user. The NavigationPane takes the ownership of the pushed page. The owner of the pushed page must be 0.

If the owner of the pushed page is not 0, or if the pushed page itself is 0, nothing will happen.

This function will emit the topChanged() signal and when the transition is finished, this function emits the pushTransitionEnded() signal.

Parameters
child	The new top child page. The parent for the page must either be 0 or this NavigationPane.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool remove (
bb::cascades::Page *page)

Removes a page from the navigation stack.

Once the page is removed, the NavigationPane no longer references it, but it is still owned by the NavigationPane. It is up to the application to either delete the removed page, transfer its ownership (by setting its parent) to another object or leave it as a child of the NavigationPane (in which case it will be deleted with the NavigationPane).

This operation will not trigger a transition effect, even if removing the top page. If a transition effect is desired, use pop() instead. The topChanged() signal will be emitted if the operation affects the top node.

Parameters
page	The page to be removed; must not be 0.

Return:

true if the page was present in the navigation stack, false otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT void resetBackButtonsVisible ()

Resets the visibility of back buttons to its default state, which is visible.

Since:

BlackBerry 10.0.0

Q_SLOT void resetPeekEnabled ()

Resets the peeking behavior of the NavigationPane to its default state, which is disabled.

Setting this property only controls whether or not peeking is enabled within the content area of the Page area of the Page. Peeking is always enabled on the Back button, even if this property is disabled.

Since:

BlackBerry 10.0.0

Q_SLOT void setBackButtonsVisible (
boolvisible)

Sets whether back buttons should be visible or not for this NavigationPane.

Parameters
visible	If true back buttons should be visible, if false back buttons should not be visible.

Since:

BlackBerry 10.0.0

Q_SLOT void setPeekEnabled (
boolenabled)

Sets whether peeking from within the current Page should be enabled.

Setting this property only controls whether or not peeking is enabled within the content area of the Page. Peeking is always enabled on the Back button, even if this property is disabled.

Parameters
enabled	If true peeking be enabled, if false peeking is disabled.

Since:

BlackBerry 10.0.0

bb::cascades::Page * top ()

Returns the current topmost page on the stack of this NavigationPane.

The NavigationPane remains as the parent of the page.

Return:

The topmost page on the NavigationPane stack. Returns 0 if the stack is empty.

Since:

BlackBerry 10.0.0

bb::cascades::AbstractA11yObject * accessibility ()

Returns the accessibility object.

Return:

The accessibility object.

Since:

BlackBerry 10.2.0

Q_INVOKABLE void addKeyListener (
bb::cascades::KeyListener *keyListener)

Adds a key listener to the AbstractPane.

AbstractPane will always take ownership as key listener should never be shared. If the key listener already belongs to the AbstractPane or the key listener is 0, nothing will happen.

Parameters
keyListener	The KeyListener to add to the AbstractPane.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void addShortcut (
bb::cascades::AbstractShortcut *shortcut)

Adds a shortcut to the AbstractPane.

AbstractPane will always take ownership as shortcuts should never be shared. If the shortcut already belongs to the AbstractPane or the shortcut is 0, nothing will happen. The order in which shortcuts are added will determine which shortcut will be triggered in case of an overlap.

Parameters
shortcut	The AbstractShortcut to add to the AbstractPane.

Since:

BlackBerry 10.1.0

Q_INVOKABLE bool builtInShortcutsEnabled ()

Returns a builtInShortcutsEnabled property value.

Return:

true if builtInShortcutsEnabled property is set to true and false otherwise

Since:

BlackBerry 10.2.0

Q_INVOKABLE void disableAllShortcuts ()

Disables all shortcuts attached to the AbstractPane.

Shortcuts that are attached afterward will use the default enabled state.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void enableAllShortcuts ()

Enables all shortcuts attached to the AbstractPane.

Since:

BlackBerry 10.1.0

virtual bool event (
QEvent *event)

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

bool isPeekedAt ()

Indicates if this AbstractPane is being peeked at.

Return:

true if being peeked at, false otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::KeyListener * keyListenerAt (
intindex)

Returns a key listener at the specified index.

Ownership of the key listener remains with the AbstractPane.

Parameters
index	The index of the key listener.

Return:

The requested key listener if the index was valid, 0 otherwise.

Since:

BlackBerry 10.1.0

Q_INVOKABLE int keyListenerCount ()

Returns the number of key listeners.

Return:

The number of key listeners.

Since:

BlackBerry 10.1.0

bb::cascades::PaneProperties * paneProperties ()

Returns the PaneProperties object for the pane.

Ownership of the PaneProperties object remains unchanged.

Return:

The PaneProperties for the pane.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void removeAllKeyListeners ()

Removes all of AbstractPane's key listeners and frees up their memory.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void removeAllShortcuts ()

Removes all of AbstractPane's shortcuts and frees up their memory.

Since:

BlackBerry 10.1.0

Q_INVOKABLE bool removeKeyListener (
bb::cascades::KeyListener *keyListener)

Removes a key listener from the AbstractPane.

Once the key listener is removed, the AbstractPane no longer references it, but it is still owned by the AbstractPane. It is up to the application to either delete the removed key listener, transfer its ownership (by setting its parent) to another object, or leave it as a child of the AbstractPane (in which case it will be deleted with the AbstractPane).

Parameters
keyListener	The KeyListener to remove.

Return:

true if the key listener was owned by the AbstractPane, false otherwise.

Since:

BlackBerry 10.1.0

Q_INVOKABLE bool removeShortcut (
bb::cascades::AbstractShortcut *shortcut)

Removes a shortcut from the AbstractPane.

Once the shortcut is removed, the AbstractPane no longer references it, but it is still owned by the AbstractPane. It is up to the application to either delete the removed shortcut, transfer its ownership (by setting its parent) to another object, or leave it as a child of the AbstractPane (in which case it will be deleted with the AbstractPane).

Parameters
shortcut	The AbstractShortcut to remove.

Return:

true if the shortcut was owned by the AbstractPane, false otherwise.

Since:

BlackBerry 10.1.0

Q_SLOT void resetBuiltInShortcutsEnabled ()

Resets a builtInShortcutsEnabled property to default value.

Default value is true.

Since:

BlackBerry 10.2.0

Q_SLOT void resetPaneProperties ()

Resets the paneProperties property for the pane to 0.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void setBuiltInShortcutEnabled (
bb::cascades::SystemShortcuts::Typetype,
boolenabled )

Sets the enabled state of the built-in shortcuts attached to the AbstractPane at a system level.

Built-in shortcuts that are attached afterward will use the specified enabled state.

Note:

Selected Built-in shortcut can be enabled or disbaled only if AbstractPane::builtInShortcutsEnabled property is set to true.

Parameters
type	The system shortcut type
enabled	If true the shortcut is enabled, and if false the shortcut is disabled.

Since:

BlackBerry 10.2.0

Q_SLOT void setBuiltInShortcutsEnabled (
boolenabled)

Sets the enabled state of all built-in shortcut attached to the AbstractPane at a system level.

Parameters
enabled	If true all built-in shortcuts are enabled, and if false all shortcut are disabled.

Since:

BlackBerry 10.2.0

void setObjectName (
const QString &name)

Sets the objectName property.

Parameters
name	The new name for the object.

Since:

BlackBerry 10.0.0

Q_SLOT void setPaneProperties (
bb::cascades::PaneProperties *paneProperties)

Sets the paneProperties property for the pane.

The pane takes ownership of the PaneProperties object if no other pane owns it already. If the PaneProperties object already has an owner, the properties are applied to the pane, but ownership of the PaneProperties object remains unchanged. If the pane already owns a PaneProperties object, the existing settings are replaced by the specified PaneProperties object and the pane retains ownership of both.

Parameters
paneProperties	The new PaneProperties for the pane.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::AbstractShortcut * shortcutAt (
intindex)

Returns a shortcut at the specified index.

Ownership of the shortcut remains with the AbstractPane.

Parameters
index	The index of the shortcut.

Return:

The requested shortcut if the index was valid, 0 otherwise.

Since:

BlackBerry 10.1.0

Q_INVOKABLE int shortcutCount ()

Returns the number of shortcuts.

Return:

The number of shortcuts.

Since:

BlackBerry 10.1.0

virtual Q_INVOKABLE QString toDebugString ()

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

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

Static Public Functions

Builder create ()

Creates and returns a builder for constructing a NavigationPane.

Using the builder to create a NavigationPane:

 NavigationPane* navigationPane = NavigationPane::create();

Return:

A builder used for constructing a NavigationPane.

Since:

BlackBerry 10.0.0

Protected Functions

(Only has inherited protected functions)

BaseObject (
QObject *parent)

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)

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)

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 backButtonsVisibleChanged (
boolvisible)

Emitted when the visibility of back buttons has changed for this NavigationPane.

Parameters
visible	If true back buttons are visible, if false back buttons are not visible.

Since:

BlackBerry 10.0.0

void navigateToTransitionEnded (
QVariantListpages)

Emitted when one or more pages have been removed from the stack of this NavigationPane as a result of a call to navigateTo() on this NavigationPane.

The NavigationPane keeps the ownership of the removed pages, but they can be deleted if they are no longer needed. Furthermore, in order to be able to push a removed Page to another control, its parent must first be set to zero.

Parameters
pages	A QVariantList containing the pages that were removed. Pages deleted before this signal is emitted are excluded from the list.

Since:

BlackBerry 10.0.0

void peekEnabledChanged (
boolenabled)

Emitted when peeking on the NavigationPane is enabled or disabled.

Parameters
enabled	If true peeking is enabled, if false peeking is disabled.

Since:

BlackBerry 10.0.0

void popTransitionEnded (
bb::cascades::Page *page)

Emitted when a page has been popped from the stack of this NavigationPane.

If the Page was removed from the stack as a result of a navigateTo() call on this NavigationPane, the navigateToTransitionEnded() signal is emitted instead.

The NavigationPane keeps the ownership of the Page, but it can be deleted if it's no longer needed. Furthermore, in order to be able to push the popped Page to another control, its parent must first be set to zero.

Parameters
page	The page that was popped. 0 if the page has already been deleted.

Since:

BlackBerry 10.0.0

void pushTransitionEnded (
bb::cascades::Page *page)

Emitted when a page has been pushed onto the stack of this NavigationPane.

Parameters
page	The page that was pushed.

Since:

BlackBerry 10.0.0

void topChanged (
bb::cascades::Page *page)

Emitted when the topmost page on the stack of this NavigationPane has changed.

This signal will be emitted as soon as the stack changes. This occurs when the pop(), and push() functions are called. This signal is also emitted when the back button is pressed.

Parameters
page	The new topmost page in the navigation stack if the stack is not empty, 0 otherwise.

Since:

BlackBerry 10.0.0

void builtInShortcutsEnabledChanged (
boolbuiltInShortcutsEnabled)

Emitted when the builtInShortcutsEnabled property changes.

Parameters
builtInShortcutsEnabled	The new value.

Since:

BlackBerry 10.2.0

void creationCompleted ()

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 (
const QString &objectName)

This signal is emitted when the objectName property is changed.

See also:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0

void panePropertiesChanged (
bb::cascades::PaneProperties *paneProperties)

Emitted when the paneProperties of the pane changes.

Parameters
paneProperties	The new PaneProperties for the AbstractPane.

Since:

BlackBerry 10.0.0

void peekedAtChanged (
boolpeekedAt)

Emitted when the peekedAt property of this AbstractPane changes.

Parameters
peekedAt	If true the AbstractPane is being peeked at, otherwise false.

Since:

BlackBerry 10.0.0

void peekEnded ()

Emitted when a peek on this AbstractPane ends.

Since:

BlackBerry 10.0.0

void peekStarted ()

Emitted when a peek on this AbstractPane starts.

Since:

BlackBerry 10.0.0

NavigationPane

Overview

Inheritance

QML properties

QML signals

Properties Index

Public Functions Index

Static Public Functions Index

Protected Functions Index

Signals Index

Properties

bool backButtonsVisible

bool peekEnabled

bb::cascades::Page top[read-only]

bb::cascades::AbstractA11yObject accessibility[read-only]

QDeclarativeListProperty< QObject > attachedObjects[read-only]

QDeclarativeListProperty keyListeners[read-only]

bool builtInShortcutsEnabled

QString objectName

bb::cascades::PaneProperties paneProperties

QObject parent[read-only]

bool peekedAt[read-only]

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

Public Functions

NavigationPane (QObject *parent)

virtual~NavigationPane ()

Q_INVOKABLE bb::cascades::Page * at (intindex)

bool backButtonsVisible ()

Q_INVOKABLE int count ()

Q_INVOKABLE int indexOf (bb::cascades::Page *page)

Q_INVOKABLE void insert (intindex, bb::cascades::Page *page )

bool isPeekEnabled ()

Q_SLOT QVariantList navigateTo (bb::cascades::Page *targetPage)

Q_INVOKABLE bb::cascades::Page * pop ()

Q_INVOKABLE void push (bb::cascades::Page *child)

Q_INVOKABLE bool remove (bb::cascades::Page *page)

Q_SLOT void resetBackButtonsVisible ()

Q_SLOT void resetPeekEnabled ()

Q_SLOT void setBackButtonsVisible (boolvisible)

Q_SLOT void setPeekEnabled (boolenabled)

bb::cascades::Page * top ()

bb::cascades::AbstractA11yObject * accessibility ()

Q_INVOKABLE void addKeyListener (bb::cascades::KeyListener *keyListener)

Q_INVOKABLE void addShortcut (bb::cascades::AbstractShortcut *shortcut)

Q_INVOKABLE bool builtInShortcutsEnabled ()

Q_INVOKABLE void disableAllShortcuts ()

Q_INVOKABLE void enableAllShortcuts ()

virtual bool event (QEvent *event)

bool isPeekedAt ()

Q_INVOKABLE bb::cascades::KeyListener * keyListenerAt (intindex)

Q_INVOKABLE int keyListenerCount ()

bb::cascades::PaneProperties * paneProperties ()

Q_INVOKABLE void removeAllKeyListeners ()

Q_INVOKABLE void removeAllShortcuts ()

Q_INVOKABLE bool removeKeyListener (bb::cascades::KeyListener *keyListener)

Q_INVOKABLE bool removeShortcut (bb::cascades::AbstractShortcut *shortcut)

Q_SLOT void resetBuiltInShortcutsEnabled ()

Q_SLOT void resetPaneProperties ()

Q_INVOKABLE void setBuiltInShortcutEnabled (bb::cascades::SystemShortcuts::Typetype, boolenabled )

Q_SLOT void setBuiltInShortcutsEnabled (boolenabled)

void setObjectName (const QString &name)

Q_SLOT void setPaneProperties (bb::cascades::PaneProperties *paneProperties)

Q_INVOKABLE bb::cascades::AbstractShortcut * shortcutAt (intindex)

Q_INVOKABLE int shortcutCount ()

virtual Q_INVOKABLE QString toDebugString ()

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

Static Public Functions

Builder create ()

Protected Functions

BaseObject (QObject *parent)

virtual void connectNotify (const char *signal)

virtual void disconnectNotify (const char *signal)

Signals

void backButtonsVisibleChanged (boolvisible)

void navigateToTransitionEnded (QVariantListpages)

void peekEnabledChanged (boolenabled)

void popTransitionEnded (bb::cascades::Page *page)

void pushTransitionEnded (bb::cascades::Page *page)

void topChanged (bb::cascades::Page *page)

void builtInShortcutsEnabledChanged (boolbuiltInShortcutsEnabled)

NavigationPane (
QObject *parent)

Q_INVOKABLE bb::cascades::Page * at (
intindex)

Q_INVOKABLE int indexOf (
bb::cascades::Page *page)

Q_INVOKABLE void insert (
intindex,
bb::cascades::Page *page )

Q_SLOT QVariantList navigateTo (
bb::cascades::Page *targetPage)

Q_INVOKABLE void push (
bb::cascades::Page *child)

Q_INVOKABLE bool remove (
bb::cascades::Page *page)

Q_SLOT void setBackButtonsVisible (
boolvisible)

Q_SLOT void setPeekEnabled (
boolenabled)

Q_INVOKABLE void addKeyListener (
bb::cascades::KeyListener *keyListener)

Q_INVOKABLE void addShortcut (
bb::cascades::AbstractShortcut *shortcut)

virtual bool event (
QEvent *event)

Q_INVOKABLE bb::cascades::KeyListener * keyListenerAt (
intindex)

Q_INVOKABLE bool removeKeyListener (
bb::cascades::KeyListener *keyListener)

Q_INVOKABLE bool removeShortcut (
bb::cascades::AbstractShortcut *shortcut)

Q_INVOKABLE void setBuiltInShortcutEnabled (
bb::cascades::SystemShortcuts::Typetype,
boolenabled )

Q_SLOT void setBuiltInShortcutsEnabled (
boolenabled)

void setObjectName (
const QString &name)

Q_SLOT void setPaneProperties (
bb::cascades::PaneProperties *paneProperties)

Q_INVOKABLE bb::cascades::AbstractShortcut * shortcutAt (
intindex)

BaseObject (
QObject *parent)

virtual void connectNotify (
const char *signal)

virtual void disconnectNotify (
const char *signal)

void backButtonsVisibleChanged (
boolvisible)

void navigateToTransitionEnded (
QVariantListpages)

void peekEnabledChanged (
boolenabled)

void popTransitionEnded (
bb::cascades::Page *page)

void pushTransitionEnded (
bb::cascades::Page *page)

void topChanged (
bb::cascades::Page *page)

void builtInShortcutsEnabledChanged (
boolbuiltInShortcutsEnabled)

void objectNameChanged (
const QString &objectName)

void panePropertiesChanged (
bb::cascades::PaneProperties *paneProperties)

void peekedAtChanged (
boolpeekedAt)