UNPKG

15.9 kBTypeScriptView Raw
1import { NavigationType, FrameBase } from './frame-common';
2import { NavigatedData, Page } from '../page';
3import { Observable, EventData } from '../../data/observable';
4import { View } from '../core/view';
5import { Transition } from '../transition';
6
7export * from './frame-interfaces';
8
9export interface NavigationData extends EventData {
10 entry?: NavigationEntry;
11 fromEntry?: NavigationEntry;
12 isBack?: boolean;
13}
14
15/**
16 * Represents the logical View unit that is responsible for navigation within an application.
17 * Nested frames are supported, enabling hierarchical navigation scenarios.
18 */
19export class Frame extends FrameBase {
20 /**
21 * @private
22 */
23 _originalBackground?: any;
24
25 /**
26 * @private
27 */
28 _saveFragmentsState?();
29
30 /**
31 * Gets a frame by id.
32 */
33 static getFrameById(id: string): Frame;
34
35 /**
36 * Gets the topmost frame in the frames stack. An application will typically has one frame instance. Multiple frames handle nested (hierarchical) navigation scenarios.
37 */
38 static topmost(): Frame;
39
40 /**
41 * Navigates back using the navigation hierarchy (if any). Updates the Frame stack as needed.
42 * This method will start from the topmost Frame and will recursively search for an instance that has the canGoBack operation available.
43 */
44 static goBack();
45
46 /**
47 * @private
48 */
49 static reloadPage(context?: ModuleContext): void;
50
51 /**
52 * @private
53 */
54 static _stack(): Array<Frame>;
55
56 /**
57 * Navigates to the previous entry (if any) in the back stack.
58 * @param to The backstack entry to navigate back to.
59 */
60 goBack(to?: BackstackEntry);
61
62 /**
63 * Checks whether the goBack operation is available.
64 */
65 canGoBack(): boolean;
66
67 /**
68 * Navigates to a Page instance as described by the module name.
69 * This method will require the module and will check for a Page property in the exports of the module.
70 * @param pageModuleName The name of the module to require starting from the application root.
71 * For example if you want to navigate to page called "myPage.js" in a folder called "subFolder" and your root folder is "app" you can call navigate method like this:
72 * const frames = require("&#64;nativescript/core/ui/frame");
73 * frames.topmost().navigate("app/subFolder/myPage");
74 */
75 navigate(pageModuleName: string);
76
77 /**
78 * Creates a new Page instance using the provided callback and navigates to that Page.
79 * @param create The function to be used to create the new Page instance.
80 */
81 navigate(create: () => Page);
82
83 /**
84 * Navigates to a Page resolved by the provided NavigationEntry object.
85 * Since there are a couple of ways to specify a Page instance through an entry, there is a resolution priority:
86 * 1. entry.moduleName
87 * 2. entry.create()
88 * @param entry The NavigationEntry instance.
89 */
90 navigate(entry: NavigationEntry);
91
92 /**
93 * Used to control the visibility the Navigation Bar in iOS and the Action Bar in Android.
94 */
95 public actionBarVisibility: 'auto' | 'never' | 'always';
96
97 /**
98 * Gets the back stack of this instance.
99 */
100 // @ts-ignore
101 backStack: Array<BackstackEntry>;
102
103 /**
104 * Gets the Page instance the Frame is currently navigated to.
105 */
106 // @ts-ignore
107 currentPage: Page;
108
109 /**
110 * Gets the NavigationEntry instance the Frame is currently navigated to.
111 */
112 // @ts-ignore
113 currentEntry: NavigationEntry;
114
115 /**
116 * Gets or sets if navigation transitions should be animated.
117 */
118 // @ts-ignore
119 animated: boolean;
120
121 /**
122 * Gets or sets the default navigation transition for this frame.
123 */
124 // @ts-ignore
125 transition: NavigationTransition;
126
127 /**
128 * Gets or sets if navigation transitions should be animated globally.
129 */
130 static defaultAnimatedNavigation: boolean;
131
132 /**
133 * Gets or sets the default NavigationTransition for all frames across the app.
134 */
135 static defaultTransition: NavigationTransition;
136
137 /**
138 * Gets the AndroidFrame object that represents the Android-specific APIs for this Frame. Valid when running on Android OS.
139 */
140 android: AndroidFrame;
141
142 /**
143 * Gets the iOSFrame object that represents the iOS-specific APIs for this Frame. Valid when running on iOS.
144 */
145 ios: iOSFrame;
146
147 /**
148 * Specify a custom UINavigationBar class (iOS only)
149 */
150 iosNavigationBarClass: any;
151 /**
152 * Specify a custom UIToolbar class (iOS only)
153 */
154 iosToolBarClass: any;
155
156 //@private
157 /**
158 * @private
159 * @param entry to check
160 */
161 isCurrent(entry: BackstackEntry): boolean;
162
163 /**
164 * @private
165 * @param entry to set as current
166 * @param navigationType
167 */
168 setCurrent(entry: BackstackEntry, navigationType: NavigationType): void;
169 /**
170 * @private
171 */
172 navigationQueueIsEmpty(): boolean;
173 /**
174 * @private
175 */
176 // @ts-ignore
177 navigationBarHeight: number;
178 /**
179 * @private
180 */
181 _animationInProgress: boolean;
182 /**
183 * @private
184 */
185 _currentEntry: BackstackEntry;
186 /**
187 * @private
188 */
189 _executingContext: NavigationContext;
190 /**
191 * @private
192 */
193 _processNavigationQueue(page: Page);
194 /**
195 * @private
196 */
197 _getIsAnimatedNavigation(entry: NavigationEntry): boolean;
198 /**
199 * @private
200 */
201 _getNavigationTransition(entry: NavigationEntry): NavigationTransition;
202 /**
203 * @private
204 */
205 _updateActionBar(page?: Page, disableNavBarAnimation?: boolean);
206 /**
207 * @private
208 * @param navigationContext
209 */
210 public performNavigation(navigationContext: NavigationContext): void;
211 /**
212 * @private
213 */
214 _getNavBarVisible(page: Page): boolean;
215 /**
216 * @private
217 */
218 _findEntryForTag(fragmentTag: string): BackstackEntry;
219 /**
220 * @private
221 */
222 _updateBackstack(entry: BackstackEntry, navigationType: NavigationType): void;
223 /**
224 * @private
225 */
226 _pushInFrameStack();
227 /**
228 * @private
229 */
230 _pushInFrameStackRecursive();
231 /**
232 * @private
233 */
234 _removeFromFrameStack();
235 //@endprivate
236
237 /**
238 * Adds a listener for the specified event name.
239 *
240 * @param eventName The name of the event.
241 * @param callback The event listener to add. Will be called when an event of
242 * the given name is raised.
243 * @param thisArg An optional parameter which, when set, will be bound as the
244 * `this` context when the callback is called. Falsy values will be not be
245 * bound.
246 */
247 on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void;
248
249 /**
250 * Raised when navigation to the page has started.
251 */
252 public on(event: 'navigatingTo', callback: (args: NavigationData) => void, thisArg?: any): void;
253
254 /**
255 * Raised when navigation to the page has finished.
256 */
257 public on(event: 'navigatedTo', callback: (args: NavigationData) => void, thisArg?: any): void;
258}
259
260/**
261 * Sets the extended androidx.fragment.app.Fragment class to the Frame and navigation routine. An instance of this class will be created to represent the Page currently visible on the srceen. This method is available only for the Android platform.
262 */
263export function setFragmentClass(clazz: any): void;
264
265/**
266 * @deprecated Use Frame.getFrameById() instead.
267 *
268 * Gets a frame by id.
269 */
270export function getFrameById(id: string): Frame;
271
272/**
273 *
274 * (Android Only) Gets a frame by internally tracked id.
275 */
276export function getFrameByNumberId(frameId: number): Frame;
277
278/**
279 * @deprecated Use Frame.topmost() instead.
280 *
281 * Gets the topmost frame in the frames stack. An application will typically has one frame instance. Multiple frames handle nested (hierarchical) navigation scenarios.
282 */
283export function topmost(): Frame;
284
285/**
286 * @deprecated Use Frame.goBack() instead.
287 *
288 * Navigates back using the navigation hierarchy (if any). Updates the Frame stack as needed.
289 * This method will start from the topmost Frame and will recursively search for an instance that has the canGoBack operation available.
290 */
291export function goBack();
292
293//@private
294/**
295 * @deprecated Use Frame._stack() instead.
296 *
297 * @private
298 */
299export function _stack(): Array<Frame>;
300//@endprivate
301
302/**
303 * Represents an entry to be used to create a view or load it form file
304 */
305export interface ViewEntry {
306 /**
307 * The name of the module containing the View instance to load. Optional.
308 */
309 moduleName?: string;
310
311 /**
312 * A function used to create the View instance. Optional.
313 */
314 create?: () => View;
315}
316/**
317 * Represents an entry in passed to navigate method.
318 */
319export interface NavigationEntry extends ViewEntry {
320 /**
321 * An object passed to the onNavigatedTo callback of the Page. Typically this is used to pass some data among pages. Optional.
322 */
323 context?: any;
324
325 /**
326 * An object to become the binding context of the page navigating to. Optional.
327 */
328 bindingContext?: any;
329
330 /**
331 * True to navigate to the new Page using animated transitions, false otherwise.
332 */
333 animated?: boolean;
334
335 /**
336 * Specifies an optional navigation transition for all platforms. If not specified, the default platform transition will be used.
337 */
338 transition?: NavigationTransition;
339
340 /**
341 * Specifies an optional navigation transition for iOS. If not specified, the default platform transition will be used.
342 */
343 transitioniOS?: NavigationTransition;
344
345 /**
346 * Specifies an optional navigation transition for Android. If not specified, the default platform transition will be used.
347 */
348 transitionAndroid?: NavigationTransition;
349
350 /**
351 * True to record the navigation in the backstack, false otherwise.
352 * If the parameter is set to false then the Page will be displayed but once navigated from it will not be able to be navigated back to.
353 */
354 backstackVisible?: boolean;
355
356 /**
357 * True to clear the navigation history, false otherwise. Very useful when navigating away from login pages.
358 */
359 clearHistory?: boolean;
360}
361
362/**
363 * Represents a context passed to navigation methods.
364 */
365export interface NavigationContext {
366 entry: BackstackEntry;
367 isBackNavigation: boolean;
368 navigationType: NavigationType;
369}
370
371/**
372 * Represents an object specifying a page navigation transition.
373 */
374export interface NavigationTransition {
375 /**
376 * Can be one of the built-in transitions:
377 * - curl (same as curlUp) (iOS only)
378 * - curlUp (iOS only)
379 * - curlDown (iOS only)
380 * - explode (Android Lollipop(21) and up only)
381 * - fade
382 * - flip (same as flipRight)
383 * - flipRight
384 * - flipLeft
385 * - slide (same as slideLeft)
386 * - slideLeft
387 * - slideRight
388 * - slideTop
389 * - slideBottom
390 */
391 name?: string;
392
393 /**
394 * An user-defined instance of the "ui/transition".Transition class.
395 */
396 instance?: Transition;
397
398 /**
399 * The length of the transition in milliseconds. If you do not specify this, the default platform transition duration will be used.
400 */
401 duration?: number;
402
403 /**
404 * An optional transition animation curve. Possible values are contained in the [AnimationCurve enumeration](https://docs.nativescript.org/api-reference/modules/_ui_enums_.animationcurve.html).
405 * Alternatively, you can pass an instance of type UIViewAnimationCurve for iOS or android.animation.TimeInterpolator for Android.
406 */
407 curve?: any;
408}
409
410/**
411 * Represents an entry in the back stack of a Frame object.
412 */
413export interface BackstackEntry {
414 entry: NavigationEntry;
415 resolvedPage: Page;
416
417 //@private
418 /**
419 * @private
420 */
421 navDepth: number;
422 /**
423 * @private
424 */
425 fragmentTag: string;
426 /**
427 * @private
428 */
429 fragment?: any;
430 /**
431 * @private
432 */
433 viewSavedState?: any;
434 /**
435 * @private
436 */
437 frameId?: number;
438 /**
439 * @private
440 */
441 recreated?: boolean;
442 //@endprivate
443}
444
445/**
446 * Represents the Android-specific Frame object, aggregated within the common Frame one.
447 * In Android there are two types of navigation - using new Activity instances or using Fragments within the main Activity.
448 * To start a new Activity, a new Frame instance should be created and navigated to the desired Page.
449 */
450export interface AndroidFrame extends Observable {
451 frameId?: any;
452
453 /**
454 * Gets the native [android ViewGroup](http://developer.android.com/reference/android/view/ViewGroup.html) instance that represents the root layout part of the Frame.
455 */
456 rootViewGroup: any /* android.view.ViewGroup */;
457
458 /**
459 * Gets the native [android Activity](http://developer.android.com/reference/android/app/Activity.html) instance associated with this Frame. In case of nested Frame objects, this property points to the activity of the root Frame.
460 */
461 activity: any /* androidx.appcompat.app.AppCompatActivity */;
462
463 /**
464 * Gets the current (foreground) activity for the application. This property will recursively traverse all existing Frame objects and check for own Activity property.
465 */
466 currentActivity: any /* androidx.appcompat.app.AppCompatActivity */;
467
468 /**
469 * Gets the actionBar property of the currentActivity.
470 */
471 actionBar: any /* android.app.ActionBar */;
472
473 /**
474 * Determines whether the Activity associated with this Frame will display an action bar or not.
475 */
476 showActionBar: boolean;
477
478 /**
479 * Finds the native androidx.fragment.app.Fragment instance created for the specified Page.
480 * @param page The Page instance to search for.
481 */
482 fragmentForPage(entry: BackstackEntry): any;
483}
484
485export interface AndroidActivityCallbacks {
486 getRootView(): View;
487 resetActivityContent(activity: any): void;
488
489 onCreate(activity: any, savedInstanceState: any, intent: any, superFunc: Function): void;
490 onSaveInstanceState(activity: any, outState: any, superFunc: Function): void;
491 onStart(activity: any, superFunc: Function): void;
492 onStop(activity: any, superFunc: Function): void;
493 onPostResume(activity: any, superFunc: Function): void;
494 onDestroy(activity: any, superFunc: Function): void;
495 onBackPressed(activity: any, superFunc: Function): void;
496 onRequestPermissionsResult(activity: any, requestCode: number, permissions: Array<string>, grantResults: Array<number>, superFunc: Function): void;
497 onActivityResult(activity: any, requestCode: number, resultCode: number, data: any, superFunc: Function);
498 onNewIntent(activity: any, intent: any, superSetIntentFunc: Function, superFunc: Function): void;
499}
500
501export interface AndroidFragmentCallbacks {
502 onHiddenChanged(fragment: any, hidden: boolean, superFunc: Function): void;
503 onCreateAnimator(fragment: any, transit: number, enter: boolean, nextAnim: number, superFunc: Function): any;
504 onCreate(fragment: any, savedInstanceState: any, superFunc: Function): void;
505 onCreateView(fragment: any, inflater: any, container: any, savedInstanceState: any, superFunc: Function): any;
506 onSaveInstanceState(fragment: any, outState: any, superFunc: Function): void;
507 onDestroyView(fragment: any, superFunc: Function): void;
508 onDestroy(fragment: any, superFunc: Function): void;
509 onPause(fragment: any, superFunc: Function): void;
510 onResume(fragment: any, superFunc: Function): void;
511 onStop(fragment: any, superFunc: Function): void;
512 toStringOverride(fragment: any, superFunc: Function): string;
513}
514
515/* tslint:disable */
516/**
517 * Represents the iOS-specific Frame object, aggregated within the common Frame one.
518 * In iOS the native controller, associated with a Frame object is UINavigationController.
519 * The navigation controller will automatically hide/show its navigation bar depending on the back stack of the Frame.
520 */
521export interface iOSFrame {
522 /**
523 * Gets the native [UINavigationController](https://developer.apple.com/library/prerelease/ios/documentation/UIKit/Reference/UINavigationController_Class/index.html) instance associated with this Frame.
524 */
525 controller: any /* UINavigationController */;
526
527 /**
528 * Gets or sets the visibility of navigationBar.
529 * Use NavBarVisibility enumeration - auto, never, always
530 */
531 navBarVisibility: 'auto' | 'never' | 'always';
532
533 //@private
534 /**
535 * @private
536 */
537 _disableNavBarAnimation: boolean;
538 //@endprivate
539}
540
541export function setActivityCallbacks(activity: any /*androidx.appcompat.app.AppCompatActivity*/): void;
542//@private
543/**
544 * @deprecated Use Frame.reloadPage() instead.
545 *
546 * @private
547 */
548export function reloadPage(context?: ModuleContext): void;
549/**
550 * @private
551 */
552export function setFragmentCallbacks(fragment: any /*androidx.fragment.app.Fragment*/): void;
553//@endprivate