UNPKG

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