From 407ff622586ef1e7788a112012b165fed4235cb6 Mon Sep 17 00:00:00 2001 From: Tim Lancina Date: Mon, 31 Aug 2015 11:09:40 -0500 Subject: [PATCH] toolbar and viewcontroller docs wip --- ionic/components/toolbar/toolbar.ts | 26 +++- ionic/components/view/view-controller.ts | 144 ++++++++++++++++++++++- ionic/components/view/view-item.ts | 125 +++++++++++++++----- 3 files changed, 264 insertions(+), 31 deletions(-) diff --git a/ionic/components/toolbar/toolbar.ts b/ionic/components/toolbar/toolbar.ts index 0885922737..076aad6ebf 100644 --- a/ionic/components/toolbar/toolbar.ts +++ b/ionic/components/toolbar/toolbar.ts @@ -4,7 +4,9 @@ import {Ion} from '../ion'; import {IonicConfig} from '../../config/config'; import {IonicComponent} from '../../config/annotations'; - +/** + * TODO + */ export class ToolbarBase extends Ion { constructor(elementRef: ElementRef, config: IonicConfig) { @@ -13,6 +15,11 @@ export class ToolbarBase extends Ion { this.itemEles = []; } + /** + * TODO + * @param {TODO} eleRef TODO + * @returns {TODO} TODO + */ titleElement(eleRef) { if (arguments.length) { this._nbTlEle = eleRef; @@ -20,6 +27,11 @@ export class ToolbarBase extends Ion { return this._nbTlEle; } + /** + * TODO + * @param {TODO} eleRef TODO + * @returns {TODO} TODO + */ itemElements(eleRef) { if (arguments.length) { this.itemEles.push(eleRef); @@ -27,6 +39,11 @@ export class ToolbarBase extends Ion { return this.itemEles; } + /** + * TODO + * @param {TODO} eleRef TODO + * @returns {TODO} TODO + */ titleText(eleRef) { if (arguments.length) { this._ttTxt.push(eleRef); @@ -34,6 +51,9 @@ export class ToolbarBase extends Ion { return this._ttTxt; } + /** + * TODO + */ alignTitle() { // don't bother if we're not trying to center align the title if (this.titleAlign !== 'center' || this.aligned) return; @@ -70,7 +90,9 @@ export class ToolbarBase extends Ion { } - +/** + * TODO + */ @IonicComponent({ selector: 'ion-toolbar' }) diff --git a/ionic/components/view/view-controller.ts b/ionic/components/view/view-controller.ts index e9ee4f3a36..ee6952cbda 100644 --- a/ionic/components/view/view-controller.ts +++ b/ionic/components/view/view-controller.ts @@ -12,7 +12,9 @@ import {Transition} from '../../transitions/transition'; import {ClickBlock} from '../../util/click-block'; import * as util from 'ionic/util'; - +/** + * TODO + */ export class ViewController extends Ion { constructor( @@ -51,6 +53,13 @@ export class ViewController extends Ion { ]); } + /** + * TODO + * @param {TODO} componentType TODO + * @param {TODO} [params={}] TODO + * @param {TODO} [opts={}] TODO + * @returns {Promise} TODO + */ push(componentType, params = {}, opts = {}) { if (!componentType || this.isTransitioning()) { return Promise.reject(); @@ -94,6 +103,11 @@ export class ViewController extends Ion { return promise; } + /** + * TODO + * @param {TODO} [opts={}] TODO + * @returns {Promise} TODO + */ pop(opts = {}) { if (this.isTransitioning() || this.items.length < 2) { return Promise.reject(); @@ -140,6 +154,9 @@ export class ViewController extends Ion { /** * Set the item stack to reflect the given component classes. + * @param {TODO} components TODO + * @param {TODO} [opts={}] TODO + * @returns {Promise} TODO */ setItems(components, opts = {}) { if (!components || !components.length) { @@ -199,6 +216,13 @@ export class ViewController extends Ion { return this.push(componentType, componentObj.params, opts); } + /** + * TODO + * @param {TODO} componentType TODO + * @param {TODO} [params={}] TODO + * @param {TODO} [opts={}] TODO + * @returns {Promise} TODO + */ setRoot(componentType, params = {}, opts = {}) { return this.setItems([{ componentType, @@ -206,6 +230,14 @@ export class ViewController extends Ion { }], opts); } + /** + * TODO + * @param {TODO} enteringItem TODO + * @param {TODO} leavingItem TODO + * @param {TODO} opts TODO + * @param {Function} callback TODO + * @returns {any} TODO + */ transition(enteringItem, leavingItem, opts, callback) { if (!enteringItem || enteringItem === leavingItem) { return callback(); @@ -275,6 +307,9 @@ export class ViewController extends Ion { } + /** + * TODO + */ swipeBackStart() { if (this.isTransitioning() || this.items.length < 2) { return; @@ -354,6 +389,10 @@ export class ViewController extends Ion { } + /** + * TODO + * @param {TODO} progress TODO + */ swipeBackProgress(progress) { if (this.sbTransition) { ClickBlock(true, 4000); @@ -361,6 +400,12 @@ export class ViewController extends Ion { } } + /** + * TODO + * @param {TODO} completeSwipeBack TODO + * @param {TODO} progress TODO + * @param {TODO} playbackRate TODO + */ swipeBackEnd(completeSwipeBack, progress, playbackRate) { // to reverse the animation use a negative playbackRate if (this.sbTransition && this.sbActive) { @@ -386,6 +431,11 @@ export class ViewController extends Ion { } } + /** + * TODO + * @param {TODO} val TODO + * @returns {TODO} TODO + */ isSwipeBackEnabled(val) { if (arguments.length) { this.sbEnabled = !!val; @@ -393,6 +443,10 @@ export class ViewController extends Ion { return this.sbEnabled; } + /** + * TODO + * @returns {TODO} TODO + */ canSwipeBack() { if (this.sbEnabled) { let activeItem = this.getActive(); @@ -403,6 +457,9 @@ export class ViewController extends Ion { return false; } + /** + * TODO + */ transitionComplete() { let destroys = []; @@ -426,6 +483,10 @@ export class ViewController extends Ion { ClickBlock(false); } + /** + * TODO + * @returns {boolean} TODO + */ isTransitioning() { let state; for (let i = 0, ii = this.items.length; i < ii; i++) { @@ -438,6 +499,10 @@ export class ViewController extends Ion { return false; } + /** + * TODO + * @returns {TODO} TODO + */ getActive() { for (let i = 0, ii = this.items.length; i < ii; i++) { if (this.items[i].state === ACTIVE_STATE) { @@ -447,6 +512,11 @@ export class ViewController extends Ion { return null; } + /** + * TODO + * @param {TODO} instance TODO + * @returns {TODO} TODO + */ getByInstance(instance) { if (instance) { for (let i = 0, ii = this.items.length; i < ii; i++) { @@ -458,6 +528,11 @@ export class ViewController extends Ion { return null; } + /** + * TODO + * @param {TODO} index TODO + * @returns {TODO} TODO + */ getByIndex(index) { if (index < this.items.length && index > -1) { return this.items[index]; @@ -465,6 +540,11 @@ export class ViewController extends Ion { return null; } + /** + * TODO + * @param {TODO} item TODO + * @returns {TODO} TODO + */ getPrevious(item) { if (item) { return this.items[ this.items.indexOf(item) - 1 ]; @@ -472,6 +552,10 @@ export class ViewController extends Ion { return null; } + /** + * TODO + * @returns {TODO} TODO + */ getStagedEnteringItem() { for (let i = 0, ii = this.items.length; i < ii; i++) { if (this.items[i].state === STAGED_ENTERING_STATE) { @@ -481,6 +565,10 @@ export class ViewController extends Ion { return null; } + /** + * TODO + * @returns {TODO} TODO + */ getStagedLeavingItem() { for (let i = 0, ii = this.items.length; i < ii; i++) { if (this.items[i].state === STAGED_LEAVING_STATE) { @@ -490,6 +578,11 @@ export class ViewController extends Ion { return null; } + /** + * TODO + * @param {TODO} nbContainer TODO + * @returns {TODO} TODO + */ navbarViewContainer(nbContainer) { if (nbContainer) { this._nbContainer = nbContainer; @@ -502,6 +595,10 @@ export class ViewController extends Ion { } } + /** + * TODO + * @returns {TODO} TODO + */ anchorElementRef() { if (arguments.length) { this._anchorER = arguments[0]; @@ -509,6 +606,10 @@ export class ViewController extends Ion { return this._anchorER; } + /** + * TODO + * @returns {TODO} TODO + */ anchorViewContainerRef() { if (arguments.length) { this._anchorVC = arguments[0]; @@ -516,6 +617,10 @@ export class ViewController extends Ion { return this._anchorVC; } + /** + * TODO + * @returns {TODO} TODO + */ childNavbar() { if (arguments.length) { this._childNavbar = arguments[0]; @@ -523,23 +628,46 @@ export class ViewController extends Ion { return this._childNavbar; } + /** + * TODO + * @param {TODO} item TODO + * @returns {TODO} TODO + */ add(item) { item.id = this.id + '-' + (++this._ids); this.items.push(item); } + /** + * TODO + * @param {TODO} itemOrIndex TODO + * @returns {TODO} TODO + */ remove(itemOrIndex) { util.array.remove(this.items, itemOrIndex); } + /** + * TODO + * @param {TODO} item TODO + * @returns {TODO} TODO + */ indexOf(item) { return this.items.indexOf(item); } + /** + * TODO + * @returns {TODO} TODO + */ length() { return this.items.length; } + /** + * TODO + * @returns {TODO} TODO + */ instances() { let instances = []; for (let item of this.items) { @@ -550,14 +678,28 @@ export class ViewController extends Ion { return instances; } + /** + * TODO + * @param {TODO} item TODO + * @returns {TODO} TODO + */ isActive(item) { return (item && item.state === ACTIVE_STATE); } + /** + * TODO + * @param {TODO} item TODO + * @returns {TODO} TODO + */ isStagedEntering(item) { return (item && item.state === STAGED_ENTERING_STATE); } + /** + * TODO + * @param {TODO} router TODO + */ registerRouter(router) { this.router = router; } diff --git a/ionic/components/view/view-item.ts b/ionic/components/view/view-item.ts index 5984369054..7b3501ae73 100644 --- a/ionic/components/view/view-item.ts +++ b/ionic/components/view/view-item.ts @@ -3,7 +3,9 @@ import {DirectiveBinding} from 'angular2/src/core/compiler/element_injector'; import {NavParams} from '../nav/nav-controller'; - +/** + * TODO + */ export class ViewItem { constructor(viewCtrl, componentType, params = {}) { @@ -21,14 +23,29 @@ export class ViewItem { this.templateRefs = {}; } + /** + * TODO + * @param {TODO} name TODO + * @param {TODO} protoViewRef TODO + */ addProtoViewRef(name, protoViewRef) { this.protos[name] = protoViewRef; } + /** + * TODO + * @param {TODO} name TODO + * @param {TODO} templateRef TODO + */ addTemplateRef(name, templateRef) { this.templateRefs[name] = templateRef; } + /** + * TODO + * @param {Function} callback TODO + * @returns {TODO} TODO + */ stage(callback) { let viewCtrl = this.viewCtrl; @@ -136,10 +153,18 @@ export class ViewItem { }); } + /** + * TODO + * @param {TODO} childPromise TODO + */ addPromise(childPromise) { this._promises.push(childPromise); } + /** + * TODO + * @param {TODO} componentProtoViewRef TODO + */ inspectStructure(componentProtoViewRef) { let navbar = false; let key = '_'; @@ -173,6 +198,10 @@ export class ViewItem { }; } + /** + * TODO + * @returns {boolean} TODO + */ enableBack() { // update if it's possible to go back from this nav item if (this.viewCtrl) { @@ -184,6 +213,10 @@ export class ViewItem { return false; } + /** + * TODO + * @param {TODO} instance TODO + */ setInstance(instance) { this.instance = instance; this.instance._viewItem = this; @@ -193,6 +226,9 @@ export class ViewItem { return (this.viewCtrl ? this.viewCtrl.indexOf(this) : -1); } + /** + * TODO + */ destroy() { for (let i = 0; i < this.disposals.length; i++) { this.disposals[i](); @@ -208,6 +244,11 @@ export class ViewItem { } } + /** + * TODO + * @param {TODO} val TODO + * @returns {TODO} TODO + */ viewElementRef(val) { if (arguments.length) { this._vwEle = val; @@ -215,6 +256,10 @@ export class ViewItem { return this._vwEle; } + /** + * TODO + * @returns {TODO} TODO + */ navbarView() { if (arguments.length) { this._nbView = arguments[0]; @@ -222,6 +267,10 @@ export class ViewItem { return this._nbView; } + /** + * TODO + * @returns {TODO} TODO + */ navbarElement() { let navbarView = this.navbarView(); if (navbarView) { @@ -229,6 +278,10 @@ export class ViewItem { } } + /** + * TODO + * @returns {TODO} TODO + */ titleElement() { let navbarView = this.navbarView(); if (navbarView) { @@ -236,6 +289,10 @@ export class ViewItem { } } + /** + * TODO + * @returns {TODO} TODO + */ backButtonElement() { let navbarView = this.navbarView(); if (navbarView) { @@ -243,6 +300,10 @@ export class ViewItem { } } + /** + * TODO + * @returns {TODO} TODO + */ backButtonTextElement() { let navbarView = this.navbarView(); if (navbarView) { @@ -250,6 +311,10 @@ export class ViewItem { } } + /** + * TODO + * @returns {TODO} TODO + */ navbarItemElements() { let navbarView = this.navbarView(); if (navbarView) { @@ -257,6 +322,10 @@ export class ViewItem { } } + /** + * TODO + * @returns {TODO} TODO + */ postRender() { // the elements are in the DOM and the browser // has rendered them in their correct locations @@ -267,28 +336,28 @@ export class ViewItem { } - /* - The view has loaded. This event only happens once per view being - created. If a view leaves but is cached, then this will not - fire again on a subsequent viewing. This method is a good place - to put your setup code for the view; however, it is not the - recommended method to use when a view becomes active. - */ + /** + * The view has loaded. This event only happens once per view being + * created. If a view leaves but is cached, then this will not + * fire again on a subsequent viewing. This method is a good place + * to put your setup code for the view; however, it is not the + * recommended method to use when a view becomes active. + */ loaded() { this.instance && this.instance.viewLoaded && this.instance.viewLoaded(); } - /* - The view is about to enter and become the active view. - */ + /** + * The view is about to enter and become the active view. + */ willEnter() { this.instance && this.instance.viewWillEnter && this.instance.viewWillEnter(); } - /* - The view has fully entered and is now the active view. This - will fire, whether it was the first load or loaded from the cache. - */ + /** + * The view has fully entered and is now the active view. This + * will fire, whether it was the first load or loaded from the cache. + */ didEnter() { let navbarView = this.navbarView(); if (navbarView) { @@ -297,31 +366,31 @@ export class ViewItem { this.instance && this.instance.viewDidEnter && this.instance.viewDidEnter(); } - /* - The view has is about to leave and no longer be the active view. - */ + /** + * The view has is about to leave and no longer be the active view. + */ willLeave() { this.instance && this.instance.viewWillLeave && this.instance.viewWillLeave(); } - /* - The view has finished leaving and is no longer the active view. This - will fire, whether it is cached or unloaded. - */ + /** + * The view has finished leaving and is no longer the active view. This + * will fire, whether it is cached or unloaded. + */ didLeave() { this.instance && this.instance.viewDidLeave && this.instance.viewDidLeave(); } - /* - The view is about to be destroyed and have its elements removed. - */ + /** + * The view is about to be destroyed and have its elements removed. + */ willUnload() { this.instance && this.instance.viewWillUnload && this.instance.viewWillUnload(); } - /* - The view has been destroyed and its elements have been removed. - */ + /** + * The view has been destroyed and its elements have been removed. + */ didUnload() { this.instance && this.instance.viewDidUnload && this.instance.viewDidUnload(); }