If you don’t like reading (or just want to get to the codeJ) you can download the StickyNote styling sample application at the end of the post.

Basics: Modifying StickyNote’s Style

Take a look at the public Properties that are exposed on the StickyNoteControl class.  Using these properties you can control various aspects of the Note’s appearance and behavior using simple Setters and Triggers.

Changing Color

If you just want to change the color of the content area (e.g. the RichTextBox or InkCanvas inside the note).  Then you can set the StickyNote’s Background property:

  <Style x:Key="OverrideBackground" TargetType="{x:Type StickyNoteControl}">

    <Setter Property="Background" Value="Yellow"/>

  </Style>

Note that this will NOT change the title bar or resize handle’s appearance.  For v1, if you want to change the appearance of TitleBar and other portions of the style that contains gradients then you will have to override the who style (see Advanced section below).

Changing the StickyNote’s behavior

Using public properties on the StickyNoteControl class and Triggers we can manipulate the behavior of the note.  Here is an example of how we can change the note behavior so that by default notes are half their normal size, and when they are focused they are full size:

  <Style

x:Key="OverrideSimpleBehavior"

TargetType="{x:Type StickyNoteControl}">

    <!-- Set a default transform on the note. -->

    <Setter Property="RenderTransform">

      <Setter.Value>

        <ScaleTransform ScaleX=".5" ScaleY=".5"/>

      </Setter.Value>

    </Setter>

    <!-- Add a trigger that changes the default transform when clicked in.-->

    <Style.Triggers>     

      <Trigger Property="StickyNoteControl.IsActive" Value="True">

        <Setter Property="RenderTransform">

          <Setter.Value>

            <ScaleTransform ScaleX="1" ScaleY="1"/>

          </Setter.Value>

        </Setter>

      </Trigger>

    </Style.Triggers>

  </Style> 

Advanced: Overriding StickyNote’s Style

While it is possible to modify a Note’s behavior by just adding some setters and triggers, if you want to do any substantial changes to the appearance you are going to have to override the full Style.

Minimum style

When overriding the StickyNote style there are some constraints on what you can do.  Namely, a text StickyNote must contain a RichTextBox and an Ink note must contain an InkCanvas.  Further, the RichTextBox and InkCanvas must be named PART_ContentControl.  The following is an example of the minimum style for a StickyNoteControl that supports both Ink and Text modes:

  <Style x:Key="MinimumStyle" TargetType="{x:Type StickyNoteControl}">

    <!-- Override default style completely -->

    <Setter Property="OverridesDefaultStyle" Value="true" />

    <Setter Property="Width" Value="100" />

    <Setter Property="Height" Value ="100" />

    <Style.Triggers>

      <Trigger

Property="StickyNoteControl.StickyNoteType"

Value="{x:Static StickyNoteType.Ink}">

        <!-- Custom template that only contains required controls -->

        <Setter Property="Template">

          <Setter.Value>

            <ControlTemplate>

                <InkCanvas

Name="PART_ContentControl"

Background="LightYellow" />

            </ControlTemplate>

          </Setter.Value>

        </Setter>

      </Trigger>

      <Trigger

Property="StickyNoteControl.StickyNoteType"

Value="{x:Static StickyNoteType.Text}">

        <Setter Property="Template">

          <Setter.Value>

            <ControlTemplate>

                <RichTextBox

Name="PART_ContentControl"

Background="LightYellow"/>

            </ControlTemplate>

          </Setter.Value>

        </Setter>

      </Trigger>

    </Style.Triggers>

  </Style>

The sky is the limit (almost)

Above I’ve given you the minimum StickyNote style, the attached project contains the FULL default StickyNote style.  Using these two pieces of information and some WPF know-how you should be able to style a StickyNote to look like anything you want.  Being a V1 product, there are of course some limitations to what you can do:

·         Can’t change the appearance of the StickyNote anchor – sorry, you’re stuck with the green anchor highlight and brackets.

·         Can’t add or modify programmatic behavior of note – there isn’t support for subclassing the StickyNote control, so you won’t be add code or modify event handler behavior.

·         Can’t change the fundamental definition of a StickyNote – our styling only supports changing the appearance and behavior of the control, but at the end of the day it will still be a control that accepts either Text or Ink input.

Hope this helps to de-mystify how you could go about changing to appearance of StickyNote’s in your application.  I’d be interested in any feedback people have on their experiences styling their StickyNotes and possibly seeing what cool designs people come up with.

Enjoy!

StickyNoteStyling.zip

You can now control highlight opacity

You probably didn’t notice, but in previous versions the opacity of your highlights was always a constant .2.   This meant that when we passed a static Brush with default opacity of 1, it will magically appear transparent in your document.  This also meant that if you wanted to customize the transparency of certain colors you were unable to do so.  As of Beta 2, we will respect whatever opacity you have defined in the brush that is passed in.  This is good news because the desired opacity for Pink probably not be the same as for Black, so now you can adjust it to your personal liking.  The impact is that if you simply pass a static system Brush as your highlight color, your highlight will be completely opaque.  Lets look at how to convert our Yellow highlight from my previous posts to behave properly in Beta 2.

The color value of Brushes.Yellow is “#FFFFFF00”.  Note that the first 2 bytes control the opacity, so its opacity is 1.  In order to have a semi transparent highlight I’ll have to create a new SolidColorBrush and set its color to have an opactity of less than 1.  First I’ll declare a new SolidColorBrush in the ResourceDictionary of my tree root:

   <Grid.Resources>
    …

    <SolidColorBrush x:Key="YellowHighlightColor" Color="#54FFFF00"/>
    …

Then I’ll pass this brush as my CommandParameter instead of the system Brush:

<Button Background="Yellow"
…
CommandParameter="{StaticResource YellowHighlightColor}"/>

Following the example above it should be straight forward how to go through and create a SolidColorBrush for each highlight color, customizing the opacity for each one.

Namespace Consolidation

The annotation schema changed a little, we consolidated and cleaned up the namespaces that were used.  The result is that a Beta 2 app cannot read annotations created by a pre-Beta 2 app.  If you are affected by this change, feel free to contact me directly for information about how to port your annotations to the new schema.

Known issues to watch out for

·         If you are running on Vista, the toolbar outlined below will crash with a NullReferenceException from ButtonChrome.cs when you try and create or delete an annotation.  This is a general theme issue with buttons executing commands which change from enabled to disabled while IsMouseOver==true.  The simplest workaround for this demo is to place all the buttons directly inside the Toolbar (e.g. remove all GroupBox and StackPanels in the example).  This will cause the ToolBar to override the default style of the buttons, shortcircuiting this bug.

·         Printing annotations on FlowDocuments doesn’t work in Beta 2 (an exception will be thrown from the XPSWriter).  There is no workaroundL, but it will be supported in later releases.

·         Printing annotations made on an XPSDocument to the Vista XPS Document Writer will succeed but annotations will be ignored, annotations should appear when sent to any other printer.  This specific scenario is something we hope to support for V1.

Hope that this helps someone outJ.  If you notice that I’ve missed something or have questions please feel free to contact me.

Adding support for printing annotations is trivial.  I would have blogged about this earlier but was reluctant because of some known issues with printing that will unfortunately be present in the upcoming Beta 2 bits.  But since some people may be interested I’ll do it anyway and add this little disclaimer:

In Feb CTP this code will work for printing annotations on both FlowDocument and FixedDocument (including XPS) content.  In Beta 2 this will work for Fixed content (including XPS) but not for Flow content.  (Of course in the RTM version is will work for both again:-)).

Enough gibber-jabber, lets look at some code. Building on the code I’ve attached for my previous sample, we'll first override the default print behavior of the DocumentViewer Print button:

<DocumentViewer Name="Viewer" Grid.Row="1">
   <DocumentViewer.CommandBindings>
      <CommandBinding Command="ApplicationCommands.Print" Executed="OnPrint" />
   </DocumentViewer.CommandBindings>
</DocumentViewer>

Now we add the event handler:

protected void OnPrint(object sender, EventArgs e)
{
   PrintDialog dialog = new PrintDialog();
   bool? result = dialog.ShowDialog();
   if (result != null && result.Value)
   {
      XpsDocumentWriter writer = PrintQueue.CreateXpsDocumentWriter(dialog.PrintQueue);
      AnnotationService service = AnnotationService.GetService(Viewer);
      AnnotationDocumentPaginator adp = new AnnotationDocumentPaginator(
                              _xpsDocument.GetFixedDocumentSequence().DocumentPaginator, 
                              service.Store);
      writer.Write(adp);
   }
}

As you can see from the sample above, annotations are added to your document printout by wrapping the basic IDocumentPaginator with an AnnotationDocumentPaginator (ADP).  Something that is transparent in this example because of the way that XPS document work is that you should always pass a copy of your Document to the AnnotationDocumentPaginator.  If you don’t then the DocumentPaginator that is being displayed will get corrupted and after printing you may no longer be able to browse the document or interact with annotations properly. 

One last note is about synchronization.  There is no synchronization built into this print api.  Therefore, if you want to implement a background print you should clone your Annotation stream and then use the AnnotationDocumentPaginator constructor which accepts a Stream.  If you just pass the AnnotationStore directly then any changes you are making the live document may be represented in the partially printed document.

In my first post I gave a high level overview of how to enable Annotations on any arbitrary document viewer.  In that example we wrote our annotations out to a static file on disk called “annotations.xml.”  This approach is going to get old really fast since we are quickly going to loose track of which annotation file goes with which document.  If you are familiar with the Xps document format, you might know that it is very closely related to ZIP format.  In fact, if you rename an .xps file to .zip you can go through and browse its contents with a normal zip browser!  So since an Xps document is actually a zip container we can actually store the annotations for an Xps document directly in the document container.  First I’ll show you how you can create an Xps document from arbitrary clipboard content and then how you can add annotations to this document and store them directly in the Xps file, at the end of this entry I’ll attach code for a simple app that brings these ideas together.

Creating an Xps Document from the clipboard contents

Here is a neat and quick way to create an Xps document for pretty much any content you can copy and paste. 

The first step is to load the Clipboad contents into a generic text container.  This example shows how we would support loading XamlPackage, Rrf, or PlainText content into a FlowDocument:

FlowDocument flowDocument = new FlowDocument();

// Make single column

flowDocument.ColumnWidth = 1000;

// Make left justified.

flowDocument.TextAlignment = TextAlignment.Left;

// Load clipboard content into FlowDocument.

TextRange textRange = new TextRange(flowDocument.ContentStart, flowDocument.ContentEnd);

if (Clipboard.ContainsData(DataFormats.XamlPackage))

{

using (Stream stream = (Stream)Clipboard.GetData(DataFormats.XamlPackage))

{

textRange.Load(stream, DataFormats.XamlPackage);

}

}

else if (Clipboard.ContainsData(DataFormats.Rtf))

{

using (Stream stream = new MemoryStream(Encoding.Default.GetBytes((string)Clipboard.GetData(DataFormats.Rtf))))

{

textRange.Load(stream, DataFormats.Rtf);

}

}

else

{

textRange.Text = Clipboard.GetText();

}

Now that we have an IDocumentPaginatorSource which contains the clipboard content, we can use an XpsDocumentWriter to create our Xps formatted document.

// Create an empty XpsDocument (this will add a Package to the PackageStore).

_xpsDocument = new XpsDocument(dialog.FileName, FileAccess.ReadWrite);

// Open a writer on the document.

XpsDocumentWriter xpsWriter = XpsDocument.CreateXpsDocumentWriter(_xpsDocument);

// Write the FlowDocument out in XPS format.

xpsWriter.Write(((IDocumentPaginatorSource)flowDocument).DocumentPaginator);

Storing Annotations in an Xps Document

Now that we have an XpsDocument, we’ll display it in the DocumentViewer control and create an AnnotationService instance for it:

Viewer.Document = _xpsDocument.GetFixedDocumentSequence();

AnnotationService service = AnnotationService.GetService(Viewer);

if (service == null)

service = new AnnotationService(Viewer);

In order to store the Annotations within the XpsDocument we’ll have to use the Packaging apis (System.IO.Packaging).  Getting a hold of our XpsDocument as a package is easy, we just get it from the PackageStore:

Package xpsPackage = PackageStore.GetPackage(_xpsDocument.Uri);

Now that we have the Package, we want to query it to see if an Annotation Part already exists.  For this example I’ve invented some path that I want to use the store my annotations, you can store the annotations wherever you would like within the package.  Try and get an existing annotation Part from the package:

Uri annotPartUri = PackUriHelper.CreatePartUri(new Uri("AnnotationStream", UriKind.Relative));

PackagePart annotPart = xpsPackage.GetPart(annotPartUri);

If no Part exists then we’ll create a new one:

annotPart = xpsPackage.CreatePart(annotPartUri, "Annotations/Stream");

Now just enable the AnnotationService on the Part stream we just retrieved/created:

AnnotationStore store = new XmlStreamStore(annotPart.GetStream());

service.Enable(store);

Ta-da, any annotations that we create will be written directly into the .xps container!

I've attached a Visual Studio project which combines the concepts above to allow you to create arbitrary Xps documents that you can annotate.  Once you get it running, just copy some content (like this blog for example) and then click “New”.  It will create an Xps document that you can create Annotations on, and your annotations will be stored directly in the document file.  Here's what it will look like:

Enjoy!

Fixed missing file in attachment - 4/24/06 3pm

AnnotatingXpsDocuments.zip

In the real world we can markup documents by highlighting content or attaching little notes.  WPF provides this capability for content that is being viewed in one of the following built in text controls:

-          FlowDocumentPageViewer

-          FlowDocumentScrollViewer

-          FlowDocumentReader

-          DocumentViewer

How do I add Annotations to my Application?

If you are using one of the previous mentioned controls then you can quickly and easily enable annotations in your app.

For this example we’ll use a FlowDocumentPageViewer because we can define a FlowDocument all in XAML.  Start with a window that looks like this:

<Window  

    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"

    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"

    Title="WPF Annotations Example"

    >

<Grid>           

      <!-- Viewer and simple content -->

      <FlowDocumentPageViewer Name="Viewer" Grid.Row="1">

        <FlowDocument>

          <Paragraph>

            This is a simple example of a flow document and how you can add annotations to one.

          </Paragraph>

          <Paragraph>

            Later we'll get more complicated content...

          </Paragraph>

        </FlowDocument>

      </FlowDocumentPageViewer>

    </Grid>

</Window>

Right now we don’t have any code, just a FlowDocumentPageViewer with a very simple document.  The steps that we will have to go through to add annotations are:

1. Create a UI for creating and deleting StickyNote and Highlight annotations.
2. Write the code behind to enable and disable the AnnotationService

(1) WPF Annotations framework provides all the apis for creating, deleting, manipulating annotations, however, it is up to the specific application developer to create/provide a UI for invoking these commands/apis.  The simplest way to construct your annotation UI is to use the Commands provided on the AnnotationService class.  First we’ll need a namespace reference to the Annotation namespace to the root element of our Window:

xmlns:annot="clr-namespace:System.Windows.Annotations;assembly=PresentationFramework"    

Now lets add a ToolBar to our app that contains some buttons that will invoke commands for creating and deleting StickyNotes (no code required):

<Grid.RowDefinitions>

   <RowDefinition Height="Auto"/>

   <RowDefinition/>

</Grid.RowDefinitions>

<ToolBarTray Grid.Row="0">

   <!-- Annotations Toolbar -->

   <ToolBar>

      <!-- StickyNote Operations -->

      <GroupBox Header="Notes">

         <StackPanel Orientation="Horizontal">

            <Button

               Content="Text" 

               Width="30"

               Command="annot:AnnotationService.CreateTextStickyNoteCommand" />

            <Button

               Content="Ink"

               Width="30"

               Command="annot:AnnotationService.CreateInkStickyNoteCommand" />

            <Button

               Content="Delete"

               Width="50"

               Command="annot:AnnotationService.DeleteStickyNotesCommand" />

          </StackPanel>

       </GroupBox>

   </ToolBar>

</ToolBarTray>

Build and run your app, you should see the toolbar at the top of the window.  All of the buttons will be disabled.  Now lets write the code to enable them.

(2) Now its time to write the code to actually turn annotations on in the application.  Add the following event handlers to you window:

<Window

    ...

    x:Class="MyNamespace.Window1"

    Loaded="OnLoaded"

    Unloaded="OnUnloaded">

Now add the code:

public partial class Window1 : Window

{

   public Window1()

   {

      InitializeComponent();

   }

   // Turn Annotations On.

   protected void OnLoaded(object sender, RoutedEventArgs e)

   {

     // Make sure that an AnnotationService isn’t already enabled.

     AnnotationService service = AnnotationService.GetService(Viewer);

     if (service == null)

     {

       // (a) Create a Stream for the annotations to be stored in.

       AnnotationStream =

         new FileStream("annotations.xml", FileMode.OpenOrCreate);

       // (b) Create an AnnotationService on our

       // FlowDocumentPageViewer.

       service = new AnnotationService(Viewer);

       // (c) Create an AnnotationStore and give it the stream we

       // created. (Autoflush == false)

       AnnotationStore store = new XmlStreamStore(AnnotationStream);

       // (d) "Turn on annotations". Annotations will be persisted in

       // the stream created at (a).

         service.Enable(store);

      }           

    }

    // Turn Annotations off.

    protected void OnUnloaded(object sender, RoutedEventArgs e)

    {

      // (a) Check that an AnnotationService actually

      // existed and was Enabled.

      AnnotationService service =

      AnnotationService.GetService(Viewer);

      if (service != null && service.IsEnabled)

      {

        // (b) Flush changes to annotations to our stream.

        service.Store.Flush();

        // (c) Turn off annotations.

        service.Disable();

        // (d) Close our stream.

        AnnotationStream.Close();

      }

    }

    // The stream that we will store annotations in.

    Stream AnnotationStream;

}

Now build and run the app. When you make a selection within the FlowDocumentPageViewer the buttons in the ToolBar we created will automatically become enabled.  Clicking “Add Text” or “Add Ink” will cause a StickyNote to be created within the document.  Annotations will be stored in the file “annotations.xml” in your CWD.  When you restart the app, your annotations will re-appear.

Note: the automatic enabling/disabling of the buttons will only occur if they are inside a ToolBar.  This is because the ToolBar does some "magic" to dynamic change the CommandTarget of its children based on the focus of the app.  If you aren't using a ToolBar then you will have to explicitly set the CommandTarget of each button so that they point to the viewer, e.g. CommandTarget="Viewer".

Lets look a little more closely at the code.  In OnLoaded, we first initialize a Stream in which to load and save annotations from.  It is important to understand that while the annotation framework will handle serializing the contents of the stream it is the appliation's responsibility to manage the Stream.  That means that the application's responsibility to open, close, ensure permissions, and provide any security on the stream.  It is also important to mention that the application should provide a different stream for each document that you are annotating.  I'll provide some specific examples in future posts, but get in your head now that you should never use an annotations stream created on DocumentA when viewing/annotating DocumentB.

Now that we have our stream we'll create an AnnotationService for the viewer that we want to enable annotations on.  AnnotationService is where all the action happens, note that there is one service per viewer, and one AnnotationStore per document. An AnnotationStore handles persisting the annotation information to disk in some way.  The only built in store is the XmlStreamStore which, as you might expect, reads and writes from a Stream.  The final step is to Enable the AnnotationService for our particular stream.

In UnLoaded event handler, we must explicitly Flush changes that we made to the Stream.  Then Disable the AnnotationService. Finally, since it is our responsibility as the Application to manage the Stream, we have to close our Stream.

And thats it.  Simple as Pie!  We can create and delete StickyNote annotations on a FlowDocument.  Since all the code is written for enabling annotations, adding highlights is as easy writing the following xaml to our window:

Add a resources section to our grid to define a style for our Highlight buttons:

<Grid.Resources>

 <Style

   x:Key="HighlightColorButtonStyle"

   TargetType="{x:Type Button}" >

   <Setter Property="Width" Value="20" />

 </Style>

</Grid.Resources>

Add this GroupBox to  our ToolBar:

<!-- Highlight Operations -->

<GroupBox Header="Highlight">

   <StackPanel Orientation="Horizontal">

      <StackPanel Orientation="Horizontal">

         <Button Background="Yellow" Style="{StaticResource HighlightColorButtonStyle}" Command="annot:AnnotationService.CreateHighlightCommand" CommandParameter="{x:Static Brushes.Yellow}" />

         <Button Background="Green" Style="{StaticResource HighlightColorButtonStyle}" Command="annot:AnnotationService.CreateHighlightCommand" CommandParameter="{x:Static Brushes.Green}" />

         <Button Background="Red" Style="{StaticResource HighlightColorButtonStyle}" Command="annot:AnnotationService.CreateHighlightCommand" CommandParameter="{x:Static Brushes.Red}" />

         <Button Background="Blue" Style="{StaticResource HighlightColorButtonStyle}" Command="annot:AnnotationService.CreateHighlightCommand" CommandParameter="{x:Static Brushes.Blue}" />

         <Button Background="Violet" Style="{StaticResource HighlightColorButtonStyle}" Command="annot:AnnotationService.CreateHighlightCommand" CommandParameter="{x:Static Brushes.Violet}" />

       </StackPanel>

      <Button Content="Clear" Width="50" Command="annot:AnnotationService.ClearHighlightsCommand" />

    </StackPanel>

</GroupBox>

There you have it, with a small amount of code and some simple XAML for defining your UI you can now add Highlights and StickyNotes to all your FlowDocuments.  The code and UI works exactly the same for the other viewers I mentioned before.

Note that in Feb CTP there are known issues using annotations in FlowDocumentScrollViewer and FlowDocumentReader so for this release it is probably best to stick with using FlowDocumentPageViewer for annotating FlowDocuments and DocumentViewer for annotating FixedDocuments.. 

This posting is provided "AS IS" with no warranties, and confers no rights.

What is the motivation for this blog one might wonder... well quite simply it is to evanglize a, currently, little known feature of WPF called Annotations.  Everyone is very excited about the new document scenarions that WPF will enable across windows applications, but what you might not realize is that in V1 there will be a platform for adding highlights, and text/ink notes to both FixedDocuments and FlowDocuments when using any of the in box viewer controls!  This feature is available (with some glitches:-)) in the Feb CTP and will be fully functional in the soon to be release Beta 2. 

If you are using one of the following controls - DocumentViewer, FlowDocumentPageViewer, FlowDocumentScrollViewer, or FlowDocumentReader - to view text, your app could have annotations!  Samples to come...