// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
//
//
// Description:
//     SubTreeProcessor is an abstract class defining the API for 
//     processing an element tree (walking the tree and loading 
//     annotations), generating locators, and generating query
//     fragments for locator parts.  
//     Spec: Anchoring Namespace Spec.doc
//
 
using System.Windows;
using System.Windows.Annotations;
using System.Xml;
 
namespace MS.Internal.Annotations.Anchoring
{
    /// <summary>
    ///     SubTreeProcessor is an abstract class defining the API for 
    ///     processing an element tree (walking the tree and loading 
    ///     annotations), generating locators, and generating query
    ///     fragments for locator parts.  
    /// </summary>
    internal abstract class SubTreeProcessor
    {
        //------------------------------------------------------
        //
        //  Constructors
        //
        //------------------------------------------------------
 
        #region Constructors
 
        /// <summary>
        ///     Creates an instance of SubTreeProcessor.  Subclasses should
        ///     pass the manager that created and owns them.
        /// </summary>
        /// <param name="manager">the manager that owns this processor</param>
        /// <exception cref="ArgumentNullException">manager is null</exception>
        protected SubTreeProcessor(LocatorManager manager)
        {
            ArgumentNullException.ThrowIfNull(manager);
 
            _manager = manager;
        }
 
        #endregion Constructors
 
        //------------------------------------------------------
        //
        //  Public Methods
        //
        //------------------------------------------------------
 
        #region Public Methods
 
        /// <summary>
        ///     Gives the processor a chance to process annotations for this node before its
        ///     children are processed.  If calledProcessAnnotations is set to true then the
        ///     children will not be individually processed.  
        /// </summary>
        /// <param name="node">node to process</param>
        /// <param name="calledProcessAnnotations">indicates the callback was called by
        /// this processor</param>
        /// <returns>
        ///     a list of AttachedAnnotations loaded during the processing of
        ///     this node; can be null if no annotations were loaded
        /// </returns>
        /// <exception cref="ArgumentNullException">node is null</exception>
        public abstract IList<IAttachedAnnotation> PreProcessNode(DependencyObject node, out bool calledProcessAnnotations);
 
        /// <summary>
        ///   This method is always called after PreProcessSubTree and after the node's children have 
        ///   been processed (unless that step was skipped because PreProcessSubtree returned true for
        ///   calledProcessAnnotations).
        /// </summary>
        /// <param name="node">the node that is being processed</param>
        /// <param name="childrenCalledProcessAnnotations">the combined value (||'d) of calledProcessAnnotations 
        /// on this node's subtree;  in the case when the children were not individually processed, false is
        /// passed in</param>
        /// <param name="calledProcessAnnotations">indicates the callback was called by this processor</param>
        /// <returns>list of AttachedAnnotations loaded during the post processing of this node;  can
        /// be null if no annotations were loaded</returns>
        /// <exception cref="ArgumentNullException">node is null</exception>
        public virtual IList<IAttachedAnnotation> PostProcessNode(DependencyObject node, bool childrenCalledProcessAnnotations, out bool calledProcessAnnotations)
        {
            ArgumentNullException.ThrowIfNull(node);
 
            calledProcessAnnotations = false;
 
            // do nothing here
            return null;
        }
 
        /// <summary>
        ///     Generates a locator part list identifying node.  
        /// </summary>
        /// <remarks>
        ///     Most subclasses will simply return a ContentLocator with one locator
        ///     part in it.  In some cases, more than one locator part may be
        ///     required (e.g., a node which represents path to some data may
        ///     need a separate locator part for each portion of the path).
        /// </remarks>
        /// <param name="node">the node to generate a locator for</param>
        /// <param name="continueGenerating">specifies whether or not generating should 
        /// continue for the rest of the path; a SubTreeProcessor could return false if
        /// it processed the rest of the path itself </param>
        /// <returns>
        ///     a locator identifying 'node'; in most cases this locator will 
        ///     only contain one locator part; can return null if no 
        ///     locator part can be generated for the given node
        /// </returns>
        /// <exception cref="ArgumentNullException">node is null</exception>
        public abstract ContentLocator GenerateLocator(PathNode node, out bool continueGenerating);
 
        /// <summary>
        ///     Searches the logical tree for a node matching the values of 
        ///     locatorPart.  The search begins with startNode.  
        /// </summary>
        /// <remarks>
        ///     Subclasses can choose to only examine startNode or traverse
        ///     the logical tree looking for a match.  The algorithms for some
        ///     locator part types may require a search of the tree instead of
        ///     a simple examination of one node.
        /// </remarks>
        /// <param name="locatorPart">locator part to be matched, must be of the type 
        /// handled by this processor</param>
        /// <param name="startNode">logical tree node to start search at</param>
        /// <param name="continueResolving">return flag indicating whether the search 
        /// should continue (presumably because the search was not exhaustive)</param>
        /// <returns>returns a node that matches the locator part; null if no such 
        /// node is found</returns>
        /// <exception cref="ArgumentNullException">locatorPart or startNode are 
        /// null</exception>
        /// <exception cref="ArgumentException">locatorPart is of the incorrect 
        /// type</exception>
        public abstract DependencyObject ResolveLocatorPart(ContentLocatorPart locatorPart, DependencyObject startNode, out bool continueResolving);
 
        /// <summary>
        ///     Returns a list of XmlQualifiedNames representing the
        ///     the locator parts this processor can resolve/generate.
        /// </summary>
        public abstract XmlQualifiedName[] GetLocatorPartTypes();
 
        #endregion Public Methods
 
        //------------------------------------------------------
        //
        //  Public Operators
        //
        //------------------------------------------------------
 
        //------------------------------------------------------
        //
        //  Public Events
        //
        //------------------------------------------------------
 
        //------------------------------------------------------
        //
        //  Public Properties
        //
        //------------------------------------------------------
 
        //------------------------------------------------------
        //
        //  Protected Methods
        //
        //------------------------------------------------------
 
        //------------------------------------------------------
        //
        //  Protected Properties
        //
        //------------------------------------------------------
 
        #region Protected Properties
 
        /// <summary>
        ///     The manager that created and owns this processor.
        /// </summary>
        protected LocatorManager Manager
        {
            get { return _manager; }
        }
 
        #endregion Protected Properties
 
        //------------------------------------------------------
        //
        //  Private Fields
        //
        //------------------------------------------------------
 
        #region Private Fields
 
        // LocatorProcessingManager that created this subtree processor
        private LocatorManager _manager;
 
        #endregion Private Fields
    }
}