diff --git a/src/Prism.Core/Navigation/IDestructible.cs b/src/Prism.Core/Navigation/IDestructible.cs index 9d221fdea..74c838cfa 100644 --- a/src/Prism.Core/Navigation/IDestructible.cs +++ b/src/Prism.Core/Navigation/IDestructible.cs @@ -3,11 +3,26 @@ /// /// Interface for objects that require cleanup of resources prior to Disposal /// + /// + /// + /// is implemented by Views and ViewModels that need to clean up resources + /// when they are being removed or destroyed. This is particularly important in modular applications + /// where views are dynamically loaded and unloaded. + /// + /// + /// When a view is removed from a region or a dialog is closed, Prism will check if the view or its + /// ViewModel implements this interface and call the method. + /// + /// public interface IDestructible { /// /// This method allows cleanup of any resources used by your View/ViewModel /// + /// + /// This method is called when the view is being removed from a region or when a dialog is being closed. + /// Use this to unsubscribe from events, dispose of resources, or perform any other cleanup operations. + /// void Destroy(); } } diff --git a/src/Prism.Core/Navigation/Regions/INavigateAsync.cs b/src/Prism.Core/Navigation/Regions/INavigateAsync.cs index ccfc23ff9..977314153 100644 --- a/src/Prism.Core/Navigation/Regions/INavigateAsync.cs +++ b/src/Prism.Core/Navigation/Regions/INavigateAsync.cs @@ -6,20 +6,32 @@ namespace Prism.Navigation.Regions /// Provides methods to perform navigation. /// /// + /// + /// is used to request navigation within a region. Navigation can involve loading a new view, + /// activating an existing view, or passing parameters between views. + /// + /// /// Convenience overloads for the methods in this interface can be found as extension methods on the /// class. + /// /// public interface INavigateAsync { /// /// Initiates navigation to the target specified by the . /// - /// The navigation target + /// The navigation target (typically a view name or URI) /// The callback executed when the navigation request is completed. /// The navigation parameters specific to the navigation request. /// + /// + /// This method performs asynchronous navigation. The navigationCallback will be invoked after navigation completes, + /// whether successfully or with an error. + /// + /// /// Convenience overloads for this method can be found as extension methods on the /// class. + /// /// void RequestNavigate(Uri target, Action navigationCallback, INavigationParameters navigationParameters); } diff --git a/src/Prism.Core/Navigation/Regions/IRegion.cs b/src/Prism.Core/Navigation/Regions/IRegion.cs index 5ff4fe0fc..3fbbac218 100644 --- a/src/Prism.Core/Navigation/Regions/IRegion.cs +++ b/src/Prism.Core/Navigation/Regions/IRegion.cs @@ -6,36 +6,63 @@ namespace Prism.Navigation.Regions /// /// Defines a model that can be used to compose views. /// + /// + /// + /// is a key component of Prism's Region-based composition pattern. Regions act as named placeholders + /// where views can be dynamically added, removed, or swapped at runtime. This allows for flexible UI composition without + /// tightly coupling different parts of an application. + /// + /// + /// Views in a region can be managed individually or as a group. Only one view can be "Active" at a time (in most region adapters), + /// allowing for tab-like or carousel-like UI patterns. Each region has a that can be used to share data + /// between the region and its views. + /// + /// public interface IRegion : INavigateAsync, INotifyPropertyChanged { /// /// Gets a readonly view of the collection of views in the region. /// /// An of all the added views. + /// + /// This collection includes all views that have been added to the region, regardless of whether they are currently active. + /// IViewsCollection Views { get; } /// /// Gets a readonly view of the collection of all the active views in the region. /// /// An of all the active views. + /// + /// In most region adapters, this collection will contain 0 or 1 items, as only one view is typically active at a time. + /// IViewsCollection ActiveViews { get; } /// /// Gets or sets a context for the region. This value can be used by the user to share context with the views. /// /// The context value to be shared. + /// + /// The context is typically used to pass data to views or to allow views to communicate back through the region. + /// object Context { get; set; } /// /// Gets the name of the region that uniquely identifies the region within a . /// /// The name of the region. + /// + /// Region names are case-sensitive and must be unique within a region manager. + /// string Name { get; set; } /// /// Gets or sets the comparison used to sort the views. /// /// The comparison to use. + /// + /// Setting this property allows you to control the order in which views appear in the Views collection. + /// Comparison SortComparison { get; set; } ///Adds a new view to the region. @@ -44,6 +71,9 @@ public interface IRegion : INavigateAsync, INotifyPropertyChanged /// /// The view to add. /// The that is set on the view. It will be the current region manager when using this overload. + /// + /// The view is resolved from the container using the provided name. + /// IRegionManager Add(string viewName); ///Adds a new view to the region. @@ -52,6 +82,9 @@ public interface IRegion : INavigateAsync, INotifyPropertyChanged /// /// The view to add. /// The that is set on the view. It will be the current region manager when using this overload. + /// + /// The view instance is directly added to the region without resolving from the container. + /// IRegionManager Add(object view); /// @@ -60,6 +93,9 @@ public interface IRegion : INavigateAsync, INotifyPropertyChanged /// The view to add. /// The name of the view. This can be used to retrieve it later by calling . /// The that is set on the view. It will be the current region manager when using this overload. + /// + /// The view is associated with the specified name and can be retrieved later using GetView(viewName). + /// IRegionManager Add(object view, string viewName); /// @@ -69,29 +105,44 @@ public interface IRegion : INavigateAsync, INotifyPropertyChanged /// The name of the view. This can be used to retrieve it later by calling . /// When , the added view will receive a new instance of , otherwise it will use the current region manager for this region. /// The that is set on the view. + /// + /// Creating a new scope is useful when you want the view and its child regions to have a hierarchical region management structure. + /// IRegionManager Add(object view, string viewName, bool createRegionManagerScope); /// /// Removes the specified view from the region. /// /// The view to remove. + /// + /// If the view is currently active, it will be deactivated before removal. + /// void Remove(object view); /// /// Removes all views from the region. /// + /// + /// This clears the region of all views. Active views are deactivated before removal. + /// void RemoveAll(); /// /// Marks the specified view as active. /// /// The view to activate. + /// + /// In most region adapters, only one view can be active at a time. Activating a new view deactivates the previously active view. + /// void Activate(object view); /// /// Marks the specified view as inactive. /// /// The view to deactivate. + /// + /// Deactivating a view removes it from the ActiveViews collection. + /// void Deactivate(object view); /// diff --git a/src/Prism.Core/Navigation/Regions/IRegionAware.cs b/src/Prism.Core/Navigation/Regions/IRegionAware.cs index ce6f51e2a..136e4f23c 100644 --- a/src/Prism.Core/Navigation/Regions/IRegionAware.cs +++ b/src/Prism.Core/Navigation/Regions/IRegionAware.cs @@ -3,27 +3,49 @@ namespace Prism.Navigation.Regions /// /// Provides a way for objects involved in navigation to be notified of navigation activities. /// + /// + /// + /// is typically implemented by ViewModel classes that need to respond to navigation events. + /// It allows views and their ViewModels to participate in the navigation lifecycle. + /// + /// + /// When a view is navigated to or away from, the region will check if its ViewModel implements this interface + /// and call the appropriate methods. + /// + /// public interface IRegionAware { /// /// Called when the implementer has been navigated to. /// - /// The navigation context. + /// The navigation context containing parameters and other navigation information. + /// + /// This method is called after the view has been added to the region and is about to be activated. + /// Use this method to initialize the view based on navigation parameters. + /// void OnNavigatedTo(NavigationContext navigationContext); /// /// Called to determine if this instance can handle the navigation request. /// - /// The navigation context. + /// The navigation context containing parameters and other navigation information. /// - /// if this instance accepts the navigation request; otherwise, . + /// if this instance accepts the navigation request and should be reused; otherwise, to create a new instance. /// + /// + /// Return if this view should be reused for the navigation (e.g., showing the same item with updated parameters). + /// Return if a new instance should be created. + /// bool IsNavigationTarget(NavigationContext navigationContext); /// /// Called when the implementer is being navigated away from. /// - /// The navigation context. + /// The navigation context containing parameters and other navigation information. + /// + /// This method is called when the view is about to be deactivated or removed from the region. + /// Use this method to clean up resources or save state if needed. + /// void OnNavigatedFrom(NavigationContext navigationContext); } }