2 * Copyright(c) 2021 Samsung Electronics Co., Ltd.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
19 using System.Collections.Generic;
20 using System.ComponentModel;
21 using Tizen.NUI.BaseComponents;
22 using Tizen.NUI.Binding;
24 namespace Tizen.NUI.Components
27 /// PoppedEventArgs is a class to record <see cref="Navigator.Popped"/> event arguments which will be sent to user.
29 /// <since_tizen> 9 </since_tizen>
30 public class PoppedEventArgs : EventArgs
33 /// Page popped by Navigator.
35 /// <since_tizen> 9 </since_tizen>
36 public Page Page { get; internal set; }
40 /// The Navigator is a class which navigates pages with stack methods such as Push and Pop.
43 /// With Transition class, Navigator supports smooth transition of View pair between two Pages
44 /// by using <see cref="PushWithTransition(Page)"/> and <see cref="PopWithTransition()"/> methods.
45 /// If current top Page and next top Page have <see cref="View"/>s those have same TransitionTag,
46 /// Navigator creates smooth transition motion for them.
47 /// Navigator.Transition property can be used to set properties of the Transition such as TimePeriod and AlphaFunction.
48 /// When all transitions are finished, Navigator calls a callback methods those connected on the "TransitionFinished" event.
52 /// Navigator navigator = new Navigator()
54 /// TimePeriod = new TimePeriod(500),
55 /// AlphaFunction = new AlphaFunction(AlphaFunction.BuiltinFunctions.EaseInOutSine)
58 /// View view = new View()
60 /// TransitionOptions = new TransitionOptions()
62 /// /* Set properties for the transition of this View */
66 /// ContentPage newPage = new ContentPage()
71 /// Navigator.PushWithTransition(newPage);
74 /// <since_tizen> 9 </since_tizen>
75 public class Navigator : Control
78 /// TransitionProperty
80 [EditorBrowsable(EditorBrowsableState.Never)]
81 public static readonly BindableProperty TransitionProperty = BindableProperty.Create(nameof(Transition), typeof(Transition), typeof(Navigator), null, propertyChanged: (bindable, oldValue, newValue) =>
83 var instance = (Navigator)bindable;
86 instance.InternalTransition = newValue as Transition;
89 defaultValueCreator: (bindable) =>
91 var instance = (Navigator)bindable;
92 return instance.InternalTransition;
95 private const int DefaultTransitionDuration = 500;
97 //This will be replaced with view transition class instance.
98 private Animation curAnimation = null;
100 //This will be replaced with view transition class instance.
101 private Animation newAnimation = null;
103 private TransitionSet transitionSet = null;
105 private Transition transition = new Transition()
107 TimePeriod = new TimePeriod(DefaultTransitionDuration),
108 AlphaFunction = new AlphaFunction(AlphaFunction.BuiltinFunctions.Default),
111 private bool transitionFinished = true;
113 //TODO: Needs to consider how to remove disposed window from dictionary.
114 //Two dictionaries are required to remove disposed navigator from dictionary.
115 private static Dictionary<Window, Navigator> windowNavigator = new Dictionary<Window, Navigator>();
116 private static Dictionary<Navigator, Window> navigatorWindow = new Dictionary<Navigator, Window>();
118 private List<Page> navigationPages = new List<Page>();
121 /// Creates a new instance of a Navigator.
123 /// <since_tizen> 9 </since_tizen>
124 public Navigator() : base()
126 Layout = new AbsoluteLayout();
130 [EditorBrowsable(EditorBrowsableState.Never)]
131 public override void OnInitialize()
135 SetAccessibilityConstructor(Role.PageTabList);
139 /// An event fired when Transition has been finished.
141 /// <since_tizen> 9 </since_tizen>
142 public event EventHandler<EventArgs> TransitionFinished;
145 /// An event fired when Pop of a page has been finished.
148 /// When you free resources in the Popped event handler, please make sure if the popped page is the page you find.
150 /// <since_tizen> 9 </since_tizen>
151 public event EventHandler<PoppedEventArgs> Popped;
154 /// Returns the count of pages in Navigator.
156 /// <since_tizen> 9 </since_tizen>
157 public int PageCount => navigationPages.Count;
160 /// Transition properties for the transition of View pair having same transition tag.
162 /// <since_tizen> 9 </since_tizen>
163 public Transition Transition
167 return GetValue(TransitionProperty) as Transition;
171 SetValue(TransitionProperty, value);
172 NotifyPropertyChanged();
175 private Transition InternalTransition
188 /// Pushes a page to Navigator.
189 /// If the page is already in Navigator, then it is not pushed.
191 /// <param name="page">The page to push to Navigator.</param>
192 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
193 /// <since_tizen> 9 </since_tizen>
194 public void PushWithTransition(Page page)
196 if (!transitionFinished)
198 Tizen.Log.Error("NUI", "Transition is still not finished.\n");
204 throw new ArgumentNullException(nameof(page), "page should not be null.");
207 //Duplicate page is not pushed.
208 if (navigationPages.Contains(page)) return;
210 var topPage = Peek();
218 navigationPages.Add(page);
220 page.Navigator = this;
223 page.InvokeAppearing();
224 topPage.InvokeDisappearing();
226 transitionSet = CreateTransitions(topPage, page, true);
227 transitionSet.Finished += (object sender, EventArgs e) =>
229 if (page is DialogPage == false)
231 topPage.SetVisible(false);
234 // Need to update Content of the new page
235 ShowContentOfPage(page);
238 page.InvokeAppeared();
239 topPage.InvokeDisappeared();
240 NotifyAccessibilityStatesChangeOfPages(topPage, page);
242 transitionFinished = false;
246 /// Pops the top page from Navigator.
248 /// <returns>The popped page.</returns>
249 /// <exception cref="InvalidOperationException">Thrown when there is no page in Navigator.</exception>
250 /// <since_tizen> 9 </since_tizen>
251 public Page PopWithTransition()
253 if (!transitionFinished)
255 Tizen.Log.Error("NUI", "Transition is still not finished.\n");
259 if (navigationPages.Count == 0)
261 throw new InvalidOperationException("There is no page in Navigator.");
264 var topPage = Peek();
266 if (navigationPages.Count == 1)
270 //Invoke Popped event
271 Popped?.Invoke(this, new PoppedEventArgs() { Page = topPage });
275 var newTopPage = navigationPages[navigationPages.Count - 2];
278 newTopPage.InvokeAppearing();
279 topPage.InvokeDisappearing();
281 transitionSet = CreateTransitions(topPage, newTopPage, false);
282 transitionSet.Finished += (object sender, EventArgs e) =>
285 topPage.SetVisible(true);
287 // Need to update Content of the new page
288 ShowContentOfPage(newTopPage);
291 newTopPage.InvokeAppeared();
292 topPage.InvokeDisappeared();
294 //Invoke Popped event
295 Popped?.Invoke(this, new PoppedEventArgs() { Page = topPage });
297 transitionFinished = false;
303 /// Pushes a page to Navigator.
304 /// If the page is already in Navigator, then it is not pushed.
306 /// <param name="page">The page to push to Navigator.</param>
307 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
308 /// <since_tizen> 9 </since_tizen>
309 public void Push(Page page)
311 if (!transitionFinished)
313 Tizen.Log.Error("NUI", "Transition is still not finished.\n");
319 throw new ArgumentNullException(nameof(page), "page should not be null.");
322 //Duplicate page is not pushed.
323 if (navigationPages.Contains(page)) return;
333 navigationPages.Add(page);
335 page.Navigator = this;
338 page.InvokeAppearing();
339 curTop.InvokeDisappearing();
341 //TODO: The following transition codes will be replaced with view transition.
342 InitializeAnimation();
344 if (page is DialogPage == false)
346 curAnimation = new Animation(1000);
347 curAnimation.AnimateTo(curTop, "Opacity", 1.0f, 0, 1000);
348 curAnimation.EndAction = Animation.EndActions.StopFinal;
349 curAnimation.Finished += (object sender, EventArgs args) =>
351 curTop.SetVisible(false);
354 curTop.InvokeDisappeared();
359 page.SetVisible(true);
360 newAnimation = new Animation(1000);
361 newAnimation.AnimateTo(page, "Opacity", 1.0f, 0, 1000);
362 newAnimation.EndAction = Animation.EndActions.StopFinal;
363 newAnimation.Finished += (object sender, EventArgs e) =>
365 // Need to update Content of the new page
366 ShowContentOfPage(page);
369 page.InvokeAppeared();
370 NotifyAccessibilityStatesChangeOfPages(curTop, page);
376 ShowContentOfPage(page);
381 /// Pops the top page from Navigator.
383 /// <returns>The popped page.</returns>
384 /// <exception cref="InvalidOperationException">Thrown when there is no page in Navigator.</exception>
385 /// <since_tizen> 9 </since_tizen>
388 if (!transitionFinished)
390 Tizen.Log.Error("NUI", "Transition is still not finished.\n");
394 if (navigationPages.Count == 0)
396 throw new InvalidOperationException("There is no page in Navigator.");
401 if (navigationPages.Count == 1)
405 //Invoke Popped event
406 Popped?.Invoke(this, new PoppedEventArgs() { Page = curTop });
411 var newTop = navigationPages[navigationPages.Count - 2];
414 newTop.InvokeAppearing();
415 curTop.InvokeDisappearing();
417 //TODO: The following transition codes will be replaced with view transition.
418 InitializeAnimation();
420 if (curTop is DialogPage == false)
422 curAnimation = new Animation(1000);
423 curAnimation.AnimateTo(curTop, "Opacity", 0.0f, 0, 1000);
424 curAnimation.EndAction = Animation.EndActions.StopFinal;
425 curAnimation.Finished += (object sender, EventArgs e) =>
427 //Removes the current top page after transition is finished.
429 curTop.Opacity = 1.0f;
432 curTop.InvokeDisappeared();
434 //Invoke Popped event
435 Popped?.Invoke(this, new PoppedEventArgs() { Page = curTop });
439 newTop.Opacity = 1.0f;
440 newTop.SetVisible(true);
441 newAnimation = new Animation(1000);
442 newAnimation.AnimateTo(newTop, "Opacity", 1.0f, 0, 1000);
443 newAnimation.EndAction = Animation.EndActions.StopFinal;
444 newAnimation.Finished += (object sender, EventArgs e) =>
446 // Need to update Content of the new page
447 ShowContentOfPage(newTop);
450 newTop.InvokeAppeared();
463 /// Returns the page of the given index in Navigator.
464 /// The indices of pages in Navigator are basically the order of pushing or inserting to Navigator.
465 /// So a page's index in Navigator can be changed whenever push/insert or pop/remove occurs.
467 /// <param name="index">The index of a page in Navigator.</param>
468 /// <returns>The page of the given index in Navigator.</returns>
469 /// <exception cref="ArgumentOutOfRangeException">Thrown when the argument index is less than 0, or greater than the number of pages.</exception>
470 public Page GetPage(int index)
472 if ((index < 0) || (index > navigationPages.Count))
474 throw new ArgumentOutOfRangeException(nameof(index), "index should be greater than or equal to 0, and less than or equal to the number of pages.");
477 return navigationPages[index];
481 /// Returns the current index of the given page in Navigator.
482 /// The indices of pages in Navigator are basically the order of pushing or inserting to Navigator.
483 /// So a page's index in Navigator can be changed whenever push/insert or pop/remove occurs.
485 /// <param name="page">The page in Navigator.</param>
486 /// <returns>The index of the given page in Navigator. If the given page is not in the Navigator, then -1 is returned.</returns>
487 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
488 /// <since_tizen> 9 </since_tizen>
489 public int IndexOf(Page page)
493 throw new ArgumentNullException(nameof(page), "page should not be null.");
496 for (int i = 0; i < navigationPages.Count; i++)
498 if (navigationPages[i] == page)
508 /// Inserts a page at the specified index of Navigator.
509 /// The indices of pages in Navigator are basically the order of pushing or inserting to Navigator.
510 /// So a page's index in Navigator can be changed whenever push/insert or pop/remove occurs.
511 /// To find the current index of a page in Navigator, please use IndexOf(page).
512 /// If the page is already in Navigator, then it is not inserted.
514 /// <param name="index">The index of a page in Navigator where the page will be inserted.</param>
515 /// <param name="page">The page to insert to Navigator.</param>
516 /// <exception cref="ArgumentOutOfRangeException">Thrown when the argument index is less than 0, or greater than the number of pages.</exception>
517 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
518 /// <since_tizen> 9 </since_tizen>
519 public void Insert(int index, Page page)
521 if ((index < 0) || (index > navigationPages.Count))
523 throw new ArgumentOutOfRangeException(nameof(index), "index should be greater than or equal to 0, and less than or equal to the number of pages.");
528 throw new ArgumentNullException(nameof(page), "page should not be null.");
531 //Duplicate page is not pushed.
532 if (navigationPages.Contains(page)) return;
534 //TODO: The following transition codes will be replaced with view transition.
535 InitializeAnimation();
537 ShowContentOfPage(page);
539 if (index == PageCount)
542 page.SetVisible(true);
546 page.SetVisible(false);
550 navigationPages.Insert(index, page);
552 page.Navigator = this;
553 if (index == PageCount - 1)
557 NotifyAccessibilityStatesChangeOfPages(navigationPages[PageCount - 2], page);
561 NotifyAccessibilityStatesChangeOfPages(null, page);
567 /// Inserts a page to Navigator before an existing page.
568 /// If the page is already in Navigator, then it is not inserted.
570 /// <param name="before">The existing page, before which a page will be inserted.</param>
571 /// <param name="page">The page to insert to Navigator.</param>
572 /// <exception cref="ArgumentNullException">Thrown when the argument before is null.</exception>
573 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
574 /// <exception cref="ArgumentException">Thrown when the argument before does not exist in Navigator.</exception>
575 /// <since_tizen> 9 </since_tizen>
576 public void InsertBefore(Page before, Page page)
580 throw new ArgumentNullException(nameof(before), "before should not be null.");
585 throw new ArgumentNullException(nameof(page), "page should not be null.");
588 //Find the index of before page.
589 int beforeIndex = navigationPages.FindIndex(x => x == before);
591 //before does not exist in Navigator.
592 if (beforeIndex == -1)
594 throw new ArgumentException("before does not exist in Navigator.", nameof(before));
597 Insert(beforeIndex, page);
601 /// Removes a page from Navigator.
603 /// <param name="page">The page to remove from Navigator.</param>
604 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
605 /// <since_tizen> 9 </since_tizen>
606 public void Remove(Page page)
610 throw new ArgumentNullException(nameof(page), "page should not be null.");
613 //TODO: The following transition codes will be replaced with view transition.
614 InitializeAnimation();
616 HideContentOfPage(page);
622 navigationPages[PageCount - 2].Opacity = 1.0f;
623 navigationPages[PageCount - 2].SetVisible(true);
624 NotifyAccessibilityStatesChangeOfPages(page, navigationPages[PageCount - 2]);
626 else if (PageCount == 1)
628 NotifyAccessibilityStatesChangeOfPages(page, null);
631 page.Navigator = null;
632 navigationPages.Remove(page);
637 /// Removes a page at the specified index of Navigator.
638 /// The indices of pages in Navigator are basically the order of pushing or inserting to Navigator.
639 /// So a page's index in Navigator can be changed whenever push/insert or pop/remove occurs.
640 /// To find the current index of a page in Navigator, please use IndexOf(page).
642 /// <param name="index">The index of a page in Navigator where the page will be removed.</param>
643 /// <exception cref="ArgumentOutOfRangeException">Thrown when the index is less than 0, or greater than or equal to the number of pages.</exception>
644 /// <since_tizen> 9 </since_tizen>
645 public void RemoveAt(int index)
647 if ((index < 0) || (index >= navigationPages.Count))
649 throw new ArgumentOutOfRangeException(nameof(index), "index should be greater than or equal to 0, and less than the number of pages.");
652 Remove(navigationPages[index]);
656 /// Returns the page at the top of Navigator.
658 /// <returns>The page at the top of Navigator.</returns>
659 /// <since_tizen> 9 </since_tizen>
662 if (navigationPages.Count == 0) return null;
664 return navigationPages[navigationPages.Count - 1];
668 /// Disposes Navigator and all children on it.
670 /// <param name="type">Dispose type.</param>
671 [EditorBrowsable(EditorBrowsableState.Never)]
672 protected override void Dispose(DisposeTypes type)
679 if (type == DisposeTypes.Explicit)
681 foreach (Page page in navigationPages)
683 Utility.Dispose(page);
685 navigationPages.Clear();
689 if (navigatorWindow.TryGetValue(this, out window) == true)
691 navigatorWindow.Remove(this);
692 windowNavigator.Remove(window);
700 /// Returns the default navigator of the given window.
702 /// <returns>The default navigator of the given window.</returns>
703 /// <exception cref="ArgumentNullException">Thrown when the argument window is null.</exception>
704 /// <since_tizen> 9 </since_tizen>
705 public static Navigator GetDefaultNavigator(Window window)
709 throw new ArgumentNullException(nameof(window), "window should not be null.");
712 if (windowNavigator.ContainsKey(window) == true)
714 return windowNavigator[window];
717 var defaultNavigator = new Navigator();
718 defaultNavigator.WidthResizePolicy = ResizePolicyType.FillToParent;
719 defaultNavigator.HeightResizePolicy = ResizePolicyType.FillToParent;
720 window.Add(defaultNavigator);
721 windowNavigator.Add(window, defaultNavigator);
722 navigatorWindow.Add(defaultNavigator, window);
724 return defaultNavigator;
728 /// Create Transitions between currentTopPage and newTopPage
730 /// <param name="currentTopPage">The top page of Navigator.</param>
731 /// <param name="newTopPage">The new top page after transition.</param>
732 /// <param name="pushTransition">True if this transition is for push new page</param>
733 private TransitionSet CreateTransitions(Page currentTopPage, Page newTopPage, bool pushTransition)
735 currentTopPage.SetVisible(true);
736 newTopPage.SetVisible(true);
738 List<View> taggedViewsInNewTopPage = new List<View>();
739 RetrieveTaggedViews(taggedViewsInNewTopPage, newTopPage, true);
740 List<View> taggedViewsInCurrentTopPage = new List<View>();
741 RetrieveTaggedViews(taggedViewsInCurrentTopPage, currentTopPage, true);
743 List<KeyValuePair<View, View>> sameTaggedViewPair = new List<KeyValuePair<View, View>>();
744 foreach(View currentTopPageView in taggedViewsInCurrentTopPage)
746 bool findPair = false;
747 foreach(View newTopPageView in taggedViewsInNewTopPage)
749 if((currentTopPageView.TransitionOptions != null) && (newTopPageView.TransitionOptions != null) &&
750 currentTopPageView.TransitionOptions?.TransitionTag == newTopPageView.TransitionOptions?.TransitionTag)
752 sameTaggedViewPair.Add(new KeyValuePair<View, View>(currentTopPageView, newTopPageView));
759 taggedViewsInNewTopPage.Remove(sameTaggedViewPair[sameTaggedViewPair.Count - 1].Value);
762 foreach(KeyValuePair<View, View> pair in sameTaggedViewPair)
764 taggedViewsInCurrentTopPage.Remove(pair.Key);
767 TransitionSet newTransitionSet = new TransitionSet();
768 foreach(KeyValuePair<View, View> pair in sameTaggedViewPair)
770 TransitionItem pairTransition = transition.CreateTransition(pair.Key, pair.Value, pushTransition);
771 if(pair.Value.TransitionOptions?.TransitionWithChild ?? false)
773 pairTransition.TransitionWithChild = true;
775 newTransitionSet.AddTransition(pairTransition);
778 newTransitionSet.Finished += (object sender, EventArgs e) =>
780 if(newTopPage.Layout != null)
782 newTopPage.Layout.RequestLayout();
784 if(currentTopPage.Layout != null)
786 currentTopPage.Layout.RequestLayout();
788 transitionFinished = true;
789 InvokeTransitionFinished();
790 transitionSet.Dispose();
791 currentTopPage.Opacity = 1.0f;
794 if (!pushTransition || newTopPage is DialogPage == false)
796 View transitionView = (currentTopPage is ContentPage) ? (currentTopPage as ContentPage).Content : (currentTopPage as DialogPage).Content;
797 if (currentTopPage.DisappearingTransition != null && transitionView != null)
799 TransitionItemBase disappearingTransition = currentTopPage.DisappearingTransition.CreateTransition(transitionView, false);
800 disappearingTransition.TransitionWithChild = true;
801 newTransitionSet.AddTransition(disappearingTransition);
805 currentTopPage.SetVisible(false);
808 if (pushTransition || currentTopPage is DialogPage == false)
810 View transitionView = (newTopPage is ContentPage) ? (newTopPage as ContentPage).Content : (newTopPage as DialogPage).Content;
811 if (newTopPage.AppearingTransition != null && transitionView != null)
813 TransitionItemBase appearingTransition = newTopPage.AppearingTransition.CreateTransition(transitionView, true);
814 appearingTransition.TransitionWithChild = true;
815 newTransitionSet.AddTransition(appearingTransition);
819 newTransitionSet.Play();
821 return newTransitionSet;
825 /// Retrieve Tagged Views in the view tree.
827 /// <param name="taggedViews">Returned tagged view list..</param>
828 /// <param name="view">Root View to get tagged child View.</param>
829 /// <param name="isRoot">Flag to check current View is page or not</param>
830 private void RetrieveTaggedViews(List<View> taggedViews, View view, bool isRoot)
832 if (!isRoot && view.TransitionOptions != null)
834 if (!string.IsNullOrEmpty(view.TransitionOptions?.TransitionTag))
836 taggedViews.Add((view as View));
837 if (view.TransitionOptions.TransitionWithChild)
845 foreach (View child in view.Children)
847 RetrieveTaggedViews(taggedViews, child, false);
852 /// Notify accessibility states change of pages.
854 /// <param name="disappearedPage">Disappeared page</param>
855 /// <param name="appearedPage">Appeared page</param>
856 private void NotifyAccessibilityStatesChangeOfPages(Page disappearedPage, Page appearedPage)
858 if (disappearedPage != null)
860 disappearedPage.UnregisterDefaultLabel();
861 //We can call disappearedPage.NotifyAccessibilityStatesChange
862 //To reduce accessibility events, we are using currently highlighted view instead
863 View curHighlightedView = Accessibility.Accessibility.Instance.GetCurrentlyHighlightedView();
864 if (curHighlightedView != null)
866 curHighlightedView.NotifyAccessibilityStatesChange(AccessibilityStates.Visible | AccessibilityStates.Showing, AccessibilityStatesNotifyMode.Single);
870 if (appearedPage != null)
872 appearedPage.RegisterDefaultLabel();
873 appearedPage.NotifyAccessibilityStatesChange(AccessibilityStates.Visible | AccessibilityStates.Showing, AccessibilityStatesNotifyMode.Single);
877 internal void InvokeTransitionFinished()
879 TransitionFinished?.Invoke(this, new EventArgs());
882 //TODO: The following transition codes will be replaced with view transition.
883 private void InitializeAnimation()
885 if (curAnimation != null)
888 curAnimation.Clear();
892 if (newAnimation != null)
895 newAnimation.Clear();
900 // Show and Register Content of Page to Accessibility bridge
901 private void ShowContentOfPage(Page page)
903 View content = (page is DialogPage) ? (page as DialogPage)?.Content : (page as ContentPage)?.Content;
906 content.Show(); // Calls RegisterDefaultLabel()
910 // Hide and Remove Content of Page from Accessibility bridge
911 private void HideContentOfPage(Page page)
913 View content = (page is DialogPage) ? (page as DialogPage)?.Content : (page as ContentPage)?.Content;
916 content.Hide(); // Calls UnregisterDefaultLabel()