AttachedPropertyComments

This element is used to define the content that should appear on the auto-generated attached property member topic for a given WPF dependency property member.

Syntax

This top-level element is valid on any dependency property member. The member on which the element appears should have its own set of member-specific XML comments as well.

 
<AttachedPropertyComments>
  <summary>
  Summary description
  </summary>
  [<remarks>Optional remarks</remarks>]
  [<example>Optional examples</example>]
  [... other top-level comments elements as needed ...]
</AttachedPropertyComments>

Include any top-level XML comments elements as you would on a standard member. These elements will be formatted in an identical fashion and will appear in the auto-generated attached property member topic.

  Note

This is a custom XML comments element implemented by the Sandcastle Help File Builder. It will not appear in the list of valid elements for XML comments IntelliSense.

Remarks

Because the attached property and attached event members of WPF classes are compiler-generated, there is no way to associate XML comments with them directly without managing a standalone XML comments file. While it is possible to do this, it is less convenient than keeping the comments in the code. The help file builder provides a solution to this through its GenerateInheritedDocs tool. As part of the process of generating inherited documentation, the tool will look for attached property and attached event fields. If it finds them, it will automatically inherit their comments for the related compiler-generated members as default comments to prevent a "missing comments" warning.

In addition, if it finds comments for those field members, it will check for an AttachedPropertyComments element (for attached properties) or an AttachedEventComments element (for attached events) and, if found, will use the XML comments nested within those elements for the related compiler-generated members. This allows you to provide comments for the field member and the related compiler-generated member that are entirely different but are managed from within the code.

  Note

Because the attached property and event members are compiler-generated, you must fully qualify their names if you want to create a link to them with a see element as shown in the example below.

Example

 
/// <summary>
/// This defines the
/// <see cref="P:XMLCommentsExamples.DocumentationInheritance.AttachedEventsAndPropertiesTest.IsBroughtIntoViewWhenSelected"/>
/// attached property.
/// </summary>
/// <AttachedPropertyComments>
/// <summary>This attached property indicates whether or not a tree view item is brought into
/// view when selected.
/// </summary>
/// <value>The default value is false</value>
/// <conceptualLink target="c0346d23-f376-4948-8f9a-d17b2f1acef3" />
/// </AttachedPropertyComments>
/// <conceptualLink target="c0346d23-f376-4948-8f9a-d17b2f1acef3" />
public static readonly DependencyProperty IsBroughtIntoViewWhenSelectedProperty =
    DependencyProperty.RegisterAttached(
    "IsBroughtIntoViewWhenSelected",
    typeof(bool),
    typeof(AttachedEventsAndPropertiesTest),
    new UIPropertyMetadata(false, OnIsBroughtIntoViewWhenSelectedChanged));

/// <summary>
/// Get the property value
/// </summary>
/// <param name="treeViewItem">The tree view item</param>
/// <returns>The property value</returns>
public static bool GetIsBroughtIntoViewWhenSelected(TreeViewItem treeViewItem)
{
    return (bool)treeViewItem.GetValue(IsBroughtIntoViewWhenSelectedProperty);
}

/// <summary>
/// Sets the property value
/// </summary>
/// <param name="treeViewItem">The tree view item</param>
/// <param name="value">The property value</param>
public static void SetIsBroughtIntoViewWhenSelected(
  TreeViewItem treeViewItem, bool value)
{
    treeViewItem.SetValue(IsBroughtIntoViewWhenSelectedProperty, value);
}

/// <summary>
/// Connect or disconnect the event handler when the selected state changes
/// </summary>
/// <param name="depObj">The dependency object</param>
/// <param name="e">The event arguments</param>
static void OnIsBroughtIntoViewWhenSelectedChanged(
  DependencyObject depObj, DependencyPropertyChangedEventArgs e)
{
    TreeViewItem item = depObj as TreeViewItem;

    if(item == null)
        return;

    if(e.NewValue is bool == false)
        return;

    if((bool)e.NewValue)
        item.Selected += OnTreeViewItemSelected;
    else
        item.Selected -= OnTreeViewItemSelected;
}

/// <summary>
/// Bring the item into view
/// </summary>
/// <param name="sender">The sender of the event</param>
/// <param name="e">The event arguments</param>
static void OnTreeViewItemSelected(object sender, RoutedEventArgs e)
{
    // Only react to the Selected event raised by the TreeViewItem
    // whose IsSelected property was modified. Ignore all ancestors
    // who are merely reporting that a descendant's Selected fired.
    if(!Object.ReferenceEquals(sender, e.OriginalSource))
        return;

    TreeViewItem item = e.OriginalSource as TreeViewItem;

    if(item != null)
        item.BringIntoView();
}

See Also