File: src\Framework\MS\Internal\Annotations\Anchoring\DataIdProcessor.cs
Project: wpf\PresentationFramework.csproj (PresentationFramework)
#pragma warning disable 1634, 1691
//-----------------------------------------------------------------------------
//
// <copyright file="DataIdProcessor.cs" company="Microsoft">
//    Copyright (C) Microsoft Corporation.  All rights reserved.
// </copyright>
//
// Description:
//     DataIdProcessor walks the tree and loads annotations based on unique ids
//     identified by the DataIdProperty.  It loads annotations when it
//     reaches a leaf in the tree or when it runs into a node with the
//     FetchAnnotationsAsBatch property set to true.
//     Spec: http://team/sites/ag/Specifications/Anchoring%20Namespace%20Spec.doc
//
// History:
//  12/01/2002: magedz: Created - based on architectural discussions and design 
//                      by axelk, rruiz, magedz
//  07/22/2003: rruiz:  Ported to WCP
//  08/18/2003: rruiz:  Updated to Anchoring Namespace Spec.
//
//-----------------------------------------------------------------------------
 
using System;
using System.Diagnostics;
using System.Collections;
using System.Collections.Generic;
using System.ComponentModel;
using System.Windows;
using System.Windows.Annotations;
using System.Windows.Annotations.Storage;
using System.Windows.Markup;
using System.Windows.Threading;
using System.Xml;
 
using MS.Utility;
 
namespace MS.Internal.Annotations.Anchoring
{
    /// <summary>
    ///     DataIdProcessor walks the tree and loads annotations based on unique ids
    ///     identified by the DataIdProperty.  It loads annotations when it
    ///     reaches a leaf in the tree or when it runs into a node with the
    ///     FetchAnnotationsAsBatch property set to true.
    /// </summary>
    internal sealed class DataIdProcessor : SubTreeProcessor
    {
        //------------------------------------------------------
        //
        //  Constructors
        //
        //------------------------------------------------------
        
        #region Constructors
 
        /// <summary>
        ///     Creates an instance of DataIdProcessor.
        /// </summary>
        /// <param name="manager">the manager that owns this processor</param>
        /// <exception cref="ArgumentNullException">manager is null</exception>
        public DataIdProcessor(LocatorManager manager) : base(manager)
        {            
        }
 
        #endregion Constructors
 
        //------------------------------------------------------
        //
        //  Public Methods
        //
        //------------------------------------------------------
        
        #region Public Methods
 
        /// <summary>
        ///     If and only if the current node has a DataId set and has FetchAnnotationsAsBatch 
        ///     set to true, then all annotations for the subtree rooted at this node are loaded
        ///     at once. 
        /// </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
        ///     the node; can be null if no annotations were loaded
        /// </returns>
        /// <exception cref="ArgumentNullException">node is null</exception>
        public override IList<IAttachedAnnotation> PreProcessNode(DependencyObject node, out bool calledProcessAnnotations)
        {
            if (node == null)
                throw new ArgumentNullException("node");            
 
            // We get the local value so we can distinguish between the property
            // being set or not.  We don't want to rely on null or String.Empty because
            // those might have been the values set.
            object dataId = node.ReadLocalValue(DataIdProcessor.DataIdProperty); 
            bool fetchAsBatch = (bool) node.GetValue(FetchAnnotationsAsBatchProperty);
 
            // If the current node has an ID set on it and FetchAnnotationsAsBatch is
            // set to true, we process this node immediately and return.  All its children
            // will be processed indirectly.
            if (fetchAsBatch && dataId != DependencyProperty.UnsetValue)
            {
                calledProcessAnnotations = true;
                return Manager.ProcessAnnotations(node);
            }
 
            calledProcessAnnotations = false;
            return null;
        }
 
        /// <summary>
        ///     This method is called after PreProcessNode and after all the children
        ///     in the subtree have been processed (or skipped if PreProcessNode returns
        ///     true for calledProcessAnnotations).
        ///     If no calls to ProcessAnnotations were made for any portion of the subtree below
        ///     this node, then annotations for this node will be loaded
        /// </summary>
        /// <param name="node">the node to process</param>
        /// <param name="childrenCalledProcessAnnotations">indicates whether calledProcessAnnotations
        /// was returned as true by any node underneath this node</param>
        /// <param name="calledProcessAnnotations">indicates whether ProcessAnnotations was called
        /// by this method</param>
        /// <returns>        
        ///     a list of AttachedAnnotations loaded during the processing of
        ///     the node; can be null if no annotations were loaded
        /// </returns>
        public override IList<IAttachedAnnotation> PostProcessNode(DependencyObject node, bool childrenCalledProcessAnnotations, out bool calledProcessAnnotations)
        {
            if (node == null)
                throw new ArgumentNullException("node");
           
            // We get the local value so we can distinguish between the property
            // being set or not.  We don't want to rely on null or String.Empty because
            // those might have been the values set.
            object dataId = node.ReadLocalValue(DataIdProcessor.DataIdProperty);
            bool fetchAsBatch = (bool) node.GetValue(FetchAnnotationsAsBatchProperty);
 
            // If no children were processed, we try and process this node
            if (!fetchAsBatch && !childrenCalledProcessAnnotations && dataId != DependencyProperty.UnsetValue)
            {
                FrameworkElement nodeParent = null;
                FrameworkElement feNode = node as FrameworkElement;
                if (feNode != null)
                {
                    nodeParent = feNode.Parent as FrameworkElement;
                }
                AnnotationService service = AnnotationService.GetService(node);
                if (service != null && 
                    (service.Root == node || 
                    (nodeParent != null && service.Root == nodeParent.TemplatedParent)))
                {
                    calledProcessAnnotations = true;
                    return Manager.ProcessAnnotations(node);
                }
            }
 
            calledProcessAnnotations = false; 
            return null;
        }
 
        /// <summary>
        ///     Generates a locator part list identifying node.  If node has a
        ///     value for DataIdProperty, a locator with a single locator part
        ///     containing the id value is returned.  Otherwise null is returned.
        /// </summary>
        /// <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; always set to true</param>
        /// <returns>if node has a value for DataIdProperty, a locator with a
        /// single locator part containing the id value; null otherwise
        /// </returns>
        /// <exception cref="ArgumentNullException">node is null</exception>
        public override ContentLocator GenerateLocator(PathNode node, out bool continueGenerating)
        {
            if (node == null)
                throw new ArgumentNullException("node");            
 
            continueGenerating = true;
            
            ContentLocator locator = null;
            ContentLocatorPart newLocatorPart = CreateLocatorPart(node.Node);
            if (newLocatorPart != null)
            {
                locator = new ContentLocator();
                locator.Parts.Add(newLocatorPart);
            }
            
            return locator;
        }
 
        /// <summary>
        ///     Searches the logical tree for a node matching the values of 
        ///     locatorPart.  The search begins with startNode.  
        /// </summary>
        /// <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 override DependencyObject ResolveLocatorPart(ContentLocatorPart locatorPart, DependencyObject startNode, out bool continueResolving)
        {
            if (locatorPart == null)
                throw new ArgumentNullException("locatorPart");
 
            if (startNode == null)
                throw new ArgumentNullException("startNode");
 
            if (DataIdElementName != locatorPart.PartType)
                throw new ArgumentException(SR.Get(SRID.IncorrectLocatorPartType, locatorPart.PartType.Namespace + ":" + locatorPart.PartType.Name), "locatorPart");
 
            // Initial value
            continueResolving = true;
                     
            // Get the values from the locator part...
            string id = locatorPart.NameValuePairs[ValueAttributeName];
            if(id == null)
            {
                throw new ArgumentException(SR.Get(SRID.IncorrectLocatorPartType, locatorPart.PartType.Namespace + ":" + locatorPart.PartType.Name), "locatorPart");
            }
            
            // and from the node to examine.
            string nodeId = GetNodeId(startNode);
 
            if (nodeId != null)
            {
                if (nodeId.Equals(id))
                {
                    return startNode;
                }
                else
                {
                    // If there was a value and it didn't match,
                    // we shouldn't bother checking the subtree
                    continueResolving = false;
                }
            }
 
            return null;
        }
 
        /// <summary>
        ///     Returns a list of XmlQualifiedNames representing the
        ///     the locator parts this processor can resolve/generate.
        /// </summary>
        public override XmlQualifiedName[] GetLocatorPartTypes()
        {
            return (XmlQualifiedName[])LocatorPartTypeNames.Clone();
        }
 
        #endregion Public Methods
 
        //------------------------------------------------------
        //
        //  Public Operators
        //
        //------------------------------------------------------        
        
        //------------------------------------------------------
        //
        //  Public Events
        //
        //------------------------------------------------------       
 
        //------------------------------------------------------
        //
        //  Public Properties
        //
        //------------------------------------------------------
 
        #region Public Properties
 
        /// <summary>
        ///     Id used to register this processor with the LocatorManager.  Registration
        ///     is done by the framework and does not need to be repeated.  Use this
        ///     string in markup as the value for SubTreeProcessorIdProperty.
        /// </summary>
        public const String Id = "Id";
 
        /// <summary>
        ///     Used to specify a unique id for the data represented by a 
        ///     logical tree node.  Attach this property to the element with a
        ///     unique value.
        /// </summary>
#pragma warning suppress 7009
        public static readonly DependencyProperty DataIdProperty = 
                DependencyProperty.RegisterAttached(
                        "DataId", 
                        typeof(String), 
                        typeof(DataIdProcessor), 
                        new PropertyMetadata(
                                (string) null, 
                                new PropertyChangedCallback(OnDataIdPropertyChanged),
                                new CoerceValueCallback(CoerceDataId)));
 
        /// <summary>
        ///    Sets the value of the DataId attached property
        ///    of the LocatorManager class.
        /// </summary>
        /// <param name="d">element to which to write the attached property</param>
        /// <param name="id">the value to set</param>
        /// <exception cref="ArgumentNullException">d is null</exception>
        public static void SetDataId(DependencyObject d, String id)
        {
            if(d == null)
                throw new ArgumentNullException("d");
 
            d.SetValue(DataIdProperty, id);
        }
 
        /// <summary>
        ///    Gets the value of the DataId attached property
        ///    of the LocatorManager class.
        /// </summary>
        /// <param name="d">the object from which to read the attached property</param>
        /// <returns>the value of the DataId attached property</returns>
        /// <exception cref="ArgumentNullException">d is null</exception>
        [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
        public static String GetDataId(DependencyObject d)
        {
            if (d == null)
                throw new ArgumentNullException("d");
 
            return d.GetValue(DataIdProperty) as String;
        }
 
        /// <summary>
        ///     Property that specifies, when set to true on an element, this
        ///     processor should load all annotations for the subtree rooted
        ///     a the element as a batch.
        /// </summary>
#pragma warning suppress 7009
        public static readonly DependencyProperty FetchAnnotationsAsBatchProperty = DependencyProperty.RegisterAttached(
                "FetchAnnotationsAsBatch", 
                typeof(bool),
                typeof(DataIdProcessor),
                new FrameworkPropertyMetadata(false, FrameworkPropertyMetadataOptions.Inherits));
 
        /// <summary>
        ///    Sets the value of the FetchAnnotationsAsBatch attached property
        ///    of the LocatorManager class.
        /// </summary>
        /// <param name="d">element to which to write the attached property</param>
        /// <param name="id">the value to set</param>
        /// <exception cref="ArgumentNullException">d is null</exception>
        public static void SetFetchAnnotationsAsBatch(DependencyObject d, bool id)
        {
            if(d == null)
                throw new ArgumentNullException("d");
 
            d.SetValue(FetchAnnotationsAsBatchProperty, id);
        }
 
 
        /// <summary>
        ///    Gets the value of the FetchAnnotationsAsBatch attached property
        ///    of the LocatorManager class.
        /// </summary>
        /// <param name="d">the object from which to read the attached property</param>
        /// <returns>the value of the FetchAnnotationsAsBatch attached property</returns>
        /// <exception cref="ArgumentNullException">d is null</exception>
        [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
        public static bool GetFetchAnnotationsAsBatch(DependencyObject d)
        {
            if(d == null)
                throw new ArgumentNullException("d");
 
            return (bool)d.GetValue(FetchAnnotationsAsBatchProperty);
        }
 
        #endregion Public Properties
 
        //------------------------------------------------------
        //
        //  Private Methods
        //
        //------------------------------------------------------
 
        #region Private Methods
 
        /// <summary>
        ///    Callback triggered when a DataIdProperty value changes.
        ///    If the values are really different we unload and reload annotations
        ///    using the new value.
        /// </summary>
        private static void OnDataIdPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
        {
            String oldValue = (string) e.OldValue;
            String newValue = (string) e.NewValue;
            
            if (!String.Equals(oldValue, newValue))
            {
                // If we get here the value has changed so we reload annotations
                AnnotationService service = AnnotationService.GetService(d);
                if (service != null && service.IsEnabled)
                {
                    service.UnloadAnnotations(d);
                    service.LoadAnnotations(d);
                } 
            }
        }
 
        private static object CoerceDataId(DependencyObject d, object value)
        {
            string newValue = (string) value;
 
            return (newValue != null && newValue.Length == 0) ? null : value;
        }
        
 
        /// <summary>
        ///     Creates a DataId locator part for node.
        /// </summary>
        /// <param name="node">logical tree node for which a locator part will be created</param>
        /// <returns>a DataId locator part for node, or null if node has no
        /// value for the DataIdProperty</returns>
        /// <exception cref="ArgumentNullException">node is null</exception>
        private ContentLocatorPart CreateLocatorPart(DependencyObject node)
        {
            Debug.Assert(node != null, "DependencyObject can not be null");
 
            // Get values from the node
            string nodeId = GetNodeId(node);
            if ((nodeId == null) || (nodeId.Length == 0))
                return null;
 
            ContentLocatorPart part = new ContentLocatorPart(DataIdElementName);
 
            part.NameValuePairs.Add(ValueAttributeName, nodeId);
            return part;
        }
 
        /// <summary>
        ///     Get the value of the DataId dependency property for a
        ///     DependencyObject.
        /// </summary>       
        /// <param name="d">the object whose DataId value is to be retrieved</param>
        /// <returns>the object's DataId, if it is set, null otherwise</returns>
        internal String GetNodeId(DependencyObject d)
        {
            Debug.Assert(d != null, "DependencyObject can not be null");
 
            String id = d.GetValue(DataIdProperty) as string;
 
            // Return null if the string is empty
            if (String.IsNullOrEmpty(id))
            {
                id = null;
            }
 
            return id;
        }
 
        #endregion Private Methods
 
        //------------------------------------------------------
        //
        //  Private Fields
        //
        //------------------------------------------------------
 
        #region Private Fields
 
        /// <summary>
        ///     The type name of locator parts handled by this  handler.  
        ///     This is internal and available to the processor that
        ///     is closely aligned with this handler.
        /// </summary>
        private static readonly XmlQualifiedName DataIdElementName = new XmlQualifiedName("DataId", AnnotationXmlConstants.Namespaces.BaseSchemaNamespace);
 
        //the name of the value attribute
        private const String ValueAttributeName = "Value";
        
        // ContentLocatorPart types understood by this processor
        private static readonly XmlQualifiedName[] LocatorPartTypeNames = 												   
                new XmlQualifiedName[]
                {
                    DataIdElementName
                };
 
        #endregion Private Fields
    }
}