Structure - NavigationPane #934

Closed
tneil opened this Issue Jul 5, 2013 · 4 comments

Projects

None yet

3 participants

Member
tneil commented Jul 5, 2013

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.
navigation_pane_push_pop

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

Properties

id : String

This is the unique identifier for the NavigationPane control instance

component: bbUI.NavigationPane

This is the component type declaration for a NavigationPane. This property's value must be bbUI.NavigationPane

backButtonsVisible : Boolean

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

The back button can be set on individual pages. The back button is never visible on the first page, except when the page is invoked as a Card. This property is true by default (back buttons are visible). If no back button has been set on the current page, a default back button is used. The default back button pops the current page and deletes it when the button is clicked.

page : bbUI.Page

This is the initial Page to be shown in the NavigationPane

peekEnabled : Boolean (Still working on licensing clearance)

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

Markup Example

var navigationPane = { // bbUI.NavigationPane
    component: bbUI.NavigationPane,
    id: 'myNavigationPane',
    backButtonsVisible: false,
    peekEnabled: true,

    page: { // bbUI.Page
        component: bbUI.Page,
        id: 'screen1',
        content: [
           {  // bbUI.Label
               component: bbUI.Label,
               id: 'myLabel',
               text: 'This is a Label'
           } // end of bbUI.Label
        ]
     } // end of bbUI.Page
} // end of bbUI.NavigationPane

JavaScript Functions

top() : bbUI.Page

Returns the current topmost page on the stack of this NavigationPane

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

alert(bbUI.$('myNavigationPane').top().id)

push (child : bbUI.Page) : void

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.

This function will emit the onTopChanged() event and when the transition is finished, this function emits the onPushTransitionEnded() event.

Parameters:

  • child : The new top child page
var child = bbUI.$('pane1');
bbUI.$('myNavigationPane').push(child);

pop() : bbUI.Page

Pops the top page from the stack of this NavigationPane.

If the stack is not empty, this function raises the onTopChanged() event immediately. When the the transition is finished, the onPopTransitionEnded() event is also raised.

The popped Page can not be pushed again (e.g. another NavigationPane) until after the onPopTransitionEnded() event has been received.

Returns: The page that was popped from the navigation stack. If the navigation stack was empty, undefined is returned.

bbUI.$('myNavigationPane').pop();

navigateTo (targetPage : bbUI.Page) : [bbUI.Page]

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 raises the onTopChanged() event 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 raises the onNavigateToTransitionEnded() event.

The removed pages can not be pushed to another control (e.g. another NavigationPane) until after the onNavigateToTransitionEnded() event has been received.

Returns: Array 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 array is returned.

var target = bbUI.$('pane2');
bbUI.$('myNavigationPane').navigateTo(target);

backButtonsVisible() : Boolean

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

Returns: true if back buttons are visible, false otherwise.

alert(bbUI.$('myNavigationPane').backButtonsVisible());

setBackButtonsVisible( visible : Boolean) : void

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.
bbUI.$('myNavigationPane').setBackButtonsVisible(true);

resetBackButtonsVisible() : void

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

count() : int

Returns the number of pages in the navigation stack.

Returns: The number of pages in the navigation stack.

bbUI.$('myNavigationPane').resetBackButtonsVisible();

at (index : int) : bbUI.Page

Returns a page at the specified index.

The index starts from the bottom of the stack, so the bottom page will have index 0.

Parameters:

  • index : The index of the page

Returns: The requested page if the index was valid, undefined otherwise

var page = bbUI.$('myNavigationPane').at(2);
if (page) {
   alert(page.id);
}

indexOf (page : bbUI.Page) : int

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 undefined, -1 is returned.

Parameters:

  • page : The page to get the index from

Returns: The index of the specified page if the page is valid, undefined otherwise

var page = bbUI.$('myPage');
alert('index is: ' + bbUI.$('myNavigationPane').indexOf(page));

insert (index : int, page : bbUI.Page) : void

Inserts a page at a specified index in the NavigationPane.

The page that is passed must not be undefined 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 onTopChanged() event 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 undefined
var page = bbUI.$('myPage');
bbUI.$('myNavigationPane').insert(2, page);

remove (page : bbUI.Page) : Boolean

Removes a page from the navigation stack.

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

Parameters:

  • page : The page to be removed, must not be undefined

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

var page = bbUI.$('myPage');
if (bbUI.$('myNavigationPane').remove(page)) {
   alert('Page ' + page.id + ' successfully removed');
}

isPeekEnabled() : Boolean

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.

Returns: true if peeking is enabled, false otherwise

alert('Peek Enabled: ' + bbUI.$('myNavigationPane').isPeekEnabled());

setPeekEnabled (enabled : Boolean) : void

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 is enabled, if false peeking is disabled
bbUI.$('myNavigationPane').setPeekEnabled(true);

resetPeekEnabled() : void

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.

bbUI.$('myNavigationPane').resetPeekEnabled();

JavaScript Events

onTopChanged (page : bbUI.Page)

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

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

Parameters:

  • page : The new topmost page in the navigation stack if the stack is not empty undefined otherwise
var navigationPane = { 
    component: bbUI.NavigationPane,

    onTopChanged: function(page) {
        alert('Top page is ' + page.id);
    }

} 

onPushTransitionEnded (page: bbUI.Page)

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

Parameters:

  • page : The page that was pushed
var navigationPane = { 
    component: bbUI.NavigationPane,

    onPushTransitionEnded: function(page) {
        alert('Push transition ended for ' + page.id);
    }

} 

onPopTransitionEnded (page: bbUI.Page)

Raised 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 onNavigateToTransitionEnded() event is raised instead.

Parameters:

  • page : The page that was popped
var navigationPane = { 
    component: bbUI.NavigationPane,

    onPopTransitionEnded: function(page) {
        alert('Pop transition ended for  ' + page.id);
    }

} 

onNavigateToTransitionEnded (pages : [bbUI.Page])

Raised 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.

Parameters:

  • pages : Array containing the pages that were removed
var navigationPane = { 
    component: bbUI.NavigationPane,

    onNavigateToTransitionEnded: function(pages) {
        alert('NavigateTo transition ended for ' + pages.length +' pages');
    }

} 

onBackButonsVisibleChanged (visible : Boolean)

Raised 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.
var navigationPane = { 
    component: bbUI.NavigationPane,

    onBackButtonsVisibleChanged: function(visible) {
        alert('Back buttons visible: ' + visible);
    }

} 

onPeekEnabledChanged (enabled : Boolean)

Raised when peeking on the NavigationPane is enabled or disabled.

Parameters:

  • enabled: If true peeking is enabled, if false peeking is disabled.
var navigationPane = { 
    component: bbUI.NavigationPane,

    onPeekEnabledChanged: function(enabled) {
        alert('Peek Enabled ' + enabled);
    }

} 
This was referenced Jul 5, 2013

from where the default backButton label came? I mean translation.

@tneil Hi bro, when would this cool feature be integrated to bbui.js ? Thanks !!

Member
tneil commented Mar 17, 2014

We've been going through a few iterations and trying out some different markup. Right now we are still experimenting and testing which markup and core navigation constructs are going to be the right ones

That's awesome !!

2014-03-17 21:08 GMT+08:00 Tim Neil notifications@github.com:

We've been going through a few iterations and trying out some different
markup. Right now we are still experimenting and testing which markup and
core navigation constructs are going to be the right ones


Reply to this email directly or view it on GitHubhttps://github.com/blackberry/bbUI.js/issues/934#issuecomment-37812820
.

@tneil tneil closed this Jul 17, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment