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);
235 page.InvokeAppeared();
236 topPage.InvokeDisappeared();
237 NotifyAccessibilityStatesChangeOfPages(topPage, page);
239 transitionFinished = false;
243 /// Pops the top page from Navigator.
245 /// <returns>The popped page.</returns>
246 /// <exception cref="InvalidOperationException">Thrown when there is no page in Navigator.</exception>
247 /// <since_tizen> 9 </since_tizen>
248 public Page PopWithTransition()
250 if (!transitionFinished)
252 Tizen.Log.Error("NUI", "Transition is still not finished.\n");
256 if (navigationPages.Count == 0)
258 throw new InvalidOperationException("There is no page in Navigator.");
261 var topPage = Peek();
263 if (navigationPages.Count == 1)
267 //Invoke Popped event
268 Popped?.Invoke(this, new PoppedEventArgs() { Page = topPage });
272 var newTopPage = navigationPages[navigationPages.Count - 2];
275 newTopPage.InvokeAppearing();
276 topPage.InvokeDisappearing();
278 transitionSet = CreateTransitions(topPage, newTopPage, false);
279 transitionSet.Finished += (object sender, EventArgs e) =>
282 topPage.SetVisible(true);
285 newTopPage.InvokeAppeared();
286 topPage.InvokeDisappeared();
287 NotifyAccessibilityStatesChangeOfPages(topPage, newTopPage);
289 //Invoke Popped event
290 Popped?.Invoke(this, new PoppedEventArgs() { Page = topPage });
292 transitionFinished = false;
298 /// Pushes a page to Navigator.
299 /// If the page is already in Navigator, then it is not pushed.
301 /// <param name="page">The page to push to Navigator.</param>
302 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
303 /// <since_tizen> 9 </since_tizen>
304 public void Push(Page page)
306 if (!transitionFinished)
308 Tizen.Log.Error("NUI", "Transition is still not finished.\n");
314 throw new ArgumentNullException(nameof(page), "page should not be null.");
317 //Duplicate page is not pushed.
318 if (navigationPages.Contains(page)) return;
328 navigationPages.Add(page);
330 page.Navigator = this;
333 page.InvokeAppearing();
334 curTop.InvokeDisappearing();
336 //TODO: The following transition codes will be replaced with view transition.
337 InitializeAnimation();
339 if (page is DialogPage == false)
341 curAnimation = new Animation(1000);
342 curAnimation.AnimateTo(curTop, "Opacity", 1.0f, 0, 1000);
343 curAnimation.EndAction = Animation.EndActions.StopFinal;
344 curAnimation.Finished += (object sender, EventArgs args) =>
346 curTop.SetVisible(false);
349 curTop.InvokeDisappeared();
354 page.SetVisible(true);
355 newAnimation = new Animation(1000);
356 newAnimation.AnimateTo(page, "Opacity", 1.0f, 0, 1000);
357 newAnimation.EndAction = Animation.EndActions.StopFinal;
358 newAnimation.Finished += (object sender, EventArgs e) =>
361 page.InvokeAppeared();
362 NotifyAccessibilityStatesChangeOfPages(curTop, page);
369 /// Pops the top page from Navigator.
371 /// <returns>The popped page.</returns>
372 /// <exception cref="InvalidOperationException">Thrown when there is no page in Navigator.</exception>
373 /// <since_tizen> 9 </since_tizen>
376 if (!transitionFinished)
378 Tizen.Log.Error("NUI", "Transition is still not finished.\n");
382 if (navigationPages.Count == 0)
384 throw new InvalidOperationException("There is no page in Navigator.");
389 if (navigationPages.Count == 1)
393 //Invoke Popped event
394 Popped?.Invoke(this, new PoppedEventArgs() { Page = curTop });
399 var newTop = navigationPages[navigationPages.Count - 2];
402 newTop.InvokeAppearing();
403 curTop.InvokeDisappearing();
405 //TODO: The following transition codes will be replaced with view transition.
406 InitializeAnimation();
408 if (curTop is DialogPage == false)
410 curAnimation = new Animation(1000);
411 curAnimation.AnimateTo(curTop, "Opacity", 0.0f, 0, 1000);
412 curAnimation.EndAction = Animation.EndActions.StopFinal;
413 curAnimation.Finished += (object sender, EventArgs e) =>
415 //Removes the current top page after transition is finished.
417 curTop.Opacity = 1.0f;
420 curTop.InvokeDisappeared();
422 //Invoke Popped event
423 Popped?.Invoke(this, new PoppedEventArgs() { Page = curTop });
427 newTop.Opacity = 1.0f;
428 newTop.SetVisible(true);
429 newAnimation = new Animation(1000);
430 newAnimation.AnimateTo(newTop, "Opacity", 1.0f, 0, 1000);
431 newAnimation.EndAction = Animation.EndActions.StopFinal;
432 newAnimation.Finished += (object sender, EventArgs e) =>
435 newTop.InvokeAppeared();
436 NotifyAccessibilityStatesChangeOfPages(curTop, newTop);
449 /// Returns the page of the given index in Navigator.
450 /// The indices of pages in Navigator are basically the order of pushing or inserting to Navigator.
451 /// So a page's index in Navigator can be changed whenever push/insert or pop/remove occurs.
453 /// <param name="index">The index of a page in Navigator.</param>
454 /// <returns>The page of the given index in Navigator.</returns>
455 /// <exception cref="ArgumentOutOfRangeException">Thrown when the argument index is less than 0, or greater than the number of pages.</exception>
456 public Page GetPage(int index)
458 if ((index < 0) || (index > navigationPages.Count))
460 throw new ArgumentOutOfRangeException(nameof(index), "index should be greater than or equal to 0, and less than or equal to the number of pages.");
463 return navigationPages[index];
467 /// Returns the current index of the given page in Navigator.
468 /// The indices of pages in Navigator are basically the order of pushing or inserting to Navigator.
469 /// So a page's index in Navigator can be changed whenever push/insert or pop/remove occurs.
471 /// <param name="page">The page in Navigator.</param>
472 /// <returns>The index of the given page in Navigator. If the given page is not in the Navigator, then -1 is returned.</returns>
473 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
474 /// <since_tizen> 9 </since_tizen>
475 public int IndexOf(Page page)
479 throw new ArgumentNullException(nameof(page), "page should not be null.");
482 for (int i = 0; i < navigationPages.Count; i++)
484 if (navigationPages[i] == page)
494 /// Inserts a page at the specified index of Navigator.
495 /// The indices of pages in Navigator are basically the order of pushing or inserting to Navigator.
496 /// So a page's index in Navigator can be changed whenever push/insert or pop/remove occurs.
497 /// To find the current index of a page in Navigator, please use IndexOf(page).
498 /// If the page is already in Navigator, then it is not inserted.
500 /// <param name="index">The index of a page in Navigator where the page will be inserted.</param>
501 /// <param name="page">The page to insert to Navigator.</param>
502 /// <exception cref="ArgumentOutOfRangeException">Thrown when the argument index is less than 0, or greater than the number of pages.</exception>
503 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
504 /// <since_tizen> 9 </since_tizen>
505 public void Insert(int index, Page page)
507 if ((index < 0) || (index > navigationPages.Count))
509 throw new ArgumentOutOfRangeException(nameof(index), "index should be greater than or equal to 0, and less than or equal to the number of pages.");
514 throw new ArgumentNullException(nameof(page), "page should not be null.");
517 //Duplicate page is not pushed.
518 if (navigationPages.Contains(page)) return;
520 //TODO: The following transition codes will be replaced with view transition.
521 InitializeAnimation();
523 if (index == PageCount)
526 page.SetVisible(true);
530 page.SetVisible(false);
534 navigationPages.Insert(index, page);
536 page.Navigator = this;
540 /// Inserts a page to Navigator before an existing page.
541 /// If the page is already in Navigator, then it is not inserted.
543 /// <param name="before">The existing page, before which a page will be inserted.</param>
544 /// <param name="page">The page to insert to Navigator.</param>
545 /// <exception cref="ArgumentNullException">Thrown when the argument before is null.</exception>
546 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
547 /// <exception cref="ArgumentException">Thrown when the argument before does not exist in Navigator.</exception>
548 /// <since_tizen> 9 </since_tizen>
549 public void InsertBefore(Page before, Page page)
553 throw new ArgumentNullException(nameof(before), "before should not be null.");
558 throw new ArgumentNullException(nameof(page), "page should not be null.");
561 //Find the index of before page.
562 int beforeIndex = navigationPages.FindIndex(x => x == before);
564 //before does not exist in Navigator.
565 if (beforeIndex == -1)
567 throw new ArgumentException("before does not exist in Navigator.", nameof(before));
570 Insert(beforeIndex, page);
574 /// Removes a page from Navigator.
576 /// <param name="page">The page to remove from Navigator.</param>
577 /// <exception cref="ArgumentNullException">Thrown when the argument page is null.</exception>
578 /// <since_tizen> 9 </since_tizen>
579 public void Remove(Page page)
583 throw new ArgumentNullException(nameof(page), "page should not be null.");
586 //TODO: The following transition codes will be replaced with view transition.
587 InitializeAnimation();
589 if ((page == Peek()) && (PageCount >= 2))
591 navigationPages[PageCount - 2].Opacity = 1.0f;
592 navigationPages[PageCount - 2].SetVisible(true);
595 page.Navigator = null;
596 navigationPages.Remove(page);
601 /// Removes a page at the specified index of Navigator.
602 /// The indices of pages in Navigator are basically the order of pushing or inserting to Navigator.
603 /// So a page's index in Navigator can be changed whenever push/insert or pop/remove occurs.
604 /// To find the current index of a page in Navigator, please use IndexOf(page).
606 /// <param name="index">The index of a page in Navigator where the page will be removed.</param>
607 /// <exception cref="ArgumentOutOfRangeException">Thrown when the index is less than 0, or greater than or equal to the number of pages.</exception>
608 /// <since_tizen> 9 </since_tizen>
609 public void RemoveAt(int index)
611 if ((index < 0) || (index >= navigationPages.Count))
613 throw new ArgumentOutOfRangeException(nameof(index), "index should be greater than or equal to 0, and less than the number of pages.");
616 Remove(navigationPages[index]);
620 /// Returns the page at the top of Navigator.
622 /// <returns>The page at the top of Navigator.</returns>
623 /// <since_tizen> 9 </since_tizen>
626 if (navigationPages.Count == 0) return null;
628 return navigationPages[navigationPages.Count - 1];
632 /// Disposes Navigator and all children on it.
634 /// <param name="type">Dispose type.</param>
635 [EditorBrowsable(EditorBrowsableState.Never)]
636 protected override void Dispose(DisposeTypes type)
643 if (type == DisposeTypes.Explicit)
645 foreach (Page page in navigationPages)
647 Utility.Dispose(page);
649 navigationPages.Clear();
653 if (navigatorWindow.TryGetValue(this, out window) == true)
655 navigatorWindow.Remove(this);
656 windowNavigator.Remove(window);
664 /// Returns the default navigator of the given window.
666 /// <returns>The default navigator of the given window.</returns>
667 /// <exception cref="ArgumentNullException">Thrown when the argument window is null.</exception>
668 /// <since_tizen> 9 </since_tizen>
669 public static Navigator GetDefaultNavigator(Window window)
673 throw new ArgumentNullException(nameof(window), "window should not be null.");
676 if (windowNavigator.ContainsKey(window) == true)
678 return windowNavigator[window];
681 var defaultNavigator = new Navigator();
682 defaultNavigator.WidthResizePolicy = ResizePolicyType.FillToParent;
683 defaultNavigator.HeightResizePolicy = ResizePolicyType.FillToParent;
684 window.Add(defaultNavigator);
685 windowNavigator.Add(window, defaultNavigator);
686 navigatorWindow.Add(defaultNavigator, window);
688 return defaultNavigator;
692 /// Create Transitions between currentTopPage and newTopPage
694 /// <param name="currentTopPage">The top page of Navigator.</param>
695 /// <param name="newTopPage">The new top page after transition.</param>
696 /// <param name="pushTransition">True if this transition is for push new page</param>
697 private TransitionSet CreateTransitions(Page currentTopPage, Page newTopPage, bool pushTransition)
699 currentTopPage.SetVisible(true);
700 newTopPage.SetVisible(true);
702 List<View> taggedViewsInNewTopPage = new List<View>();
703 RetrieveTaggedViews(taggedViewsInNewTopPage, newTopPage, true);
704 List<View> taggedViewsInCurrentTopPage = new List<View>();
705 RetrieveTaggedViews(taggedViewsInCurrentTopPage, currentTopPage, true);
707 List<KeyValuePair<View, View>> sameTaggedViewPair = new List<KeyValuePair<View, View>>();
708 foreach(View currentTopPageView in taggedViewsInCurrentTopPage)
710 bool findPair = false;
711 foreach(View newTopPageView in taggedViewsInNewTopPage)
713 if((currentTopPageView.TransitionOptions != null) && (newTopPageView.TransitionOptions != null) &&
714 currentTopPageView.TransitionOptions?.TransitionTag == newTopPageView.TransitionOptions?.TransitionTag)
716 sameTaggedViewPair.Add(new KeyValuePair<View, View>(currentTopPageView, newTopPageView));
723 taggedViewsInNewTopPage.Remove(sameTaggedViewPair[sameTaggedViewPair.Count - 1].Value);
726 foreach(KeyValuePair<View, View> pair in sameTaggedViewPair)
728 taggedViewsInCurrentTopPage.Remove(pair.Key);
731 TransitionSet newTransitionSet = new TransitionSet();
732 foreach(KeyValuePair<View, View> pair in sameTaggedViewPair)
734 TransitionItem pairTransition = transition.CreateTransition(pair.Key, pair.Value, pushTransition);
735 if(pair.Value.TransitionOptions?.TransitionWithChild ?? false)
737 pairTransition.TransitionWithChild = true;
739 newTransitionSet.AddTransition(pairTransition);
742 newTransitionSet.Finished += (object sender, EventArgs e) =>
744 if(newTopPage.Layout != null)
746 newTopPage.Layout.RequestLayout();
748 if(currentTopPage.Layout != null)
750 currentTopPage.Layout.RequestLayout();
752 transitionFinished = true;
753 InvokeTransitionFinished();
754 transitionSet.Dispose();
755 currentTopPage.Opacity = 1.0f;
758 if (!pushTransition || newTopPage is DialogPage == false)
760 View transitionView = (currentTopPage is ContentPage) ? (currentTopPage as ContentPage).Content : (currentTopPage as DialogPage).Content;
761 if (currentTopPage.DisappearingTransition != null && transitionView != null)
763 TransitionItemBase disappearingTransition = currentTopPage.DisappearingTransition.CreateTransition(transitionView, false);
764 disappearingTransition.TransitionWithChild = true;
765 newTransitionSet.AddTransition(disappearingTransition);
769 currentTopPage.SetVisible(false);
772 if (pushTransition || currentTopPage is DialogPage == false)
774 View transitionView = (newTopPage is ContentPage) ? (newTopPage as ContentPage).Content : (newTopPage as DialogPage).Content;
775 if (newTopPage.AppearingTransition != null && transitionView != null)
777 TransitionItemBase appearingTransition = newTopPage.AppearingTransition.CreateTransition(transitionView, true);
778 appearingTransition.TransitionWithChild = true;
779 newTransitionSet.AddTransition(appearingTransition);
783 newTransitionSet.Play();
785 return newTransitionSet;
789 /// Retrieve Tagged Views in the view tree.
791 /// <param name="taggedViews">Returned tagged view list..</param>
792 /// <param name="view">Root View to get tagged child View.</param>
793 /// <param name="isRoot">Flag to check current View is page or not</param>
794 private void RetrieveTaggedViews(List<View> taggedViews, View view, bool isRoot)
796 if (!isRoot && view.TransitionOptions != null)
798 if (!string.IsNullOrEmpty(view.TransitionOptions?.TransitionTag))
800 taggedViews.Add((view as View));
801 if (view.TransitionOptions.TransitionWithChild)
809 foreach (View child in view.Children)
811 RetrieveTaggedViews(taggedViews, child, false);
816 /// Notify accessibility states change of pages.
818 /// <param name="disappearedPage">Disappeared page</param>
819 /// <param name="appearedPage">Appeared page</param>
820 private void NotifyAccessibilityStatesChangeOfPages(Page disappearedPage, Page appearedPage)
822 if (disappearedPage != null)
824 disappearedPage.UnregisterDefaultLabel();
825 //We can call disappearedPage.NotifyAccessibilityStatesChange
826 //To reduce accessibility events, we are using currently highlighted view instead
827 View curHighlightedView = Accessibility.Accessibility.Instance.GetCurrentlyHighlightedView();
828 if (curHighlightedView != null)
830 curHighlightedView.NotifyAccessibilityStatesChange(AccessibilityStates.Visible | AccessibilityStates.Showing, false);
834 if (appearedPage != null)
836 appearedPage.RegisterDefaultLabel();
837 appearedPage.NotifyAccessibilityStatesChange(AccessibilityStates.Visible | AccessibilityStates.Showing, false);
841 internal void InvokeTransitionFinished()
843 TransitionFinished?.Invoke(this, new EventArgs());
846 //TODO: The following transition codes will be replaced with view transition.
847 private void InitializeAnimation()
849 if (curAnimation != null)
852 curAnimation.Clear();
856 if (newAnimation != null)
859 newAnimation.Clear();