Введение в примечания WPF

Что такое примечания WPF?
В реальном мире Мы делаем разметку документов выделением текста или добавлением небольших замечаний. WPF позволяет просматривать текст следующими элементами управления:
· FlowDocumentPageViewer
· FlowDocumentScrollViewer
· FlowDocumentReader
· DocumentViewer

Как Я могу добавить примечания в мое приложение?
Если Вы используете вышеуказанные элементы управления, то можете быстро и просто создавать примечания в Вашем приложении.

В этом примере Я использовал элемент FlowDocumentPageViewer, благодаря которому можно определить FlowDocument при помощи XAML. Начнем с окна, которое выглядит примерно так:

<Window   

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

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

    Title="WPF Annotations Example" 

    >

<Grid>            

	<!-Программа просмотра и несколько предложений для примера. -->

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

        <FlowDocument>

          <Paragraph>

            Это пример отформатированного документа. Так Вы можете добавлять примечания.

          </Paragraph>

          <Paragraph>

            Позже Мы рассмотримLater более сложную разметку...

          </Paragraph>

        </FlowDocument>

      </FlowDocumentPageViewer>

    </Grid>

</Window>

</FlowDocument>
</FlowDocumentPageViewer>
</Grid>
</Window>[/code]
Сейчас у нас нет какого-либо кода, это просто пример элемента FlowDocumentPageViewer с очень простым содержанием. Ну а для того, чтобы добавить примечания, необходимо сделать следующее:

1. Создать пользовательский интерфейс при помощи инструментов StickyNote и Highlight.
2. Написать служебный код для инициализации и выключения сервиса AnnotationService.
(1) WPF предоставляет разработчикам программный интерфейс приложения (API) для создания, удаления и манипулирования примечаниями. Однако, для этого необходимо создать интерфейс, который бы вызывал команды API, что является довольно специфичной операцией. Простейший способ создать примечания - использовать класс AnnotationService. Прежде чем писать код, создадим ссылку на пространство имен Annotation, которое является корневым элементом пространства Window:

[code]xmlns:annot="clr-namespace:System.Windows.Annotations;assembly=PresentationFramework"[/code]
Сейчас добавим элемент ToolBar, содержащий несколько кнопок, которые будут вызывать команды управления StickyNotes (кода не требуется):

[code]<Grid.RowDefinitions>
<RowDefinition Height="Auto"/>
<RowDefinition/>
</Grid.RowDefinitions>

<ToolBarTray Grid.Row="0">
<!-Панель инструментов -->
<ToolBar>
<!-Операции упраления StickyNote -->
<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>[/code]
Скомпилируйте и запустите приложение. Вы увидите панель инструментов вверху окна. Все кнопки на ней будут отключены. Напишем код, чтобы их активизировать.

(2) Пришло время написать код, который бы добавлял примечная в нашем приложении. Добавьте следующих обработчиков событий:

[code]<Window
...
x:Class="MyNamespace.Window1"
Loaded="OnLoaded"
Unloaded="OnUnloaded">

Теперь добавьте следующий код:

public partial class Window1 : Window
{
public Window1()
{
InitializeComponent();
}

// Включение примечаний.
protected void OnLoaded(object sender, RoutedEventArgs e)
{
// Проверка включения примечаний.
AnnotationService service = AnnotationService.GetService(Viewer);
if (service == null)
{
// (a) Создание потока, в котором будут храниться примечания.
AnnotationStream =
new FileStream("annotations.xml", FileMode.OpenOrCreate);
// (b) Создание AnnotationService на нашем FlowDocumentPageViewer.
service = new AnnotationService(Viewer);
// (c) Создание AnnotationStore и передача ему
// созданного потока. (Autoflush == false)
AnnotationStore store = new XmlStreamStore(AnnotationStream);
// (d) "Активизация примечаний". Примечания будут храниться
// в потоке, созданном в пункте (a).
service.Enable(store);
}
}

// Выключение примечаний.
protected void OnUnloaded(object sender, RoutedEventArgs e)
{
// (a) Проверка AnnotationService на доступность.
AnnotationService service =
AnnotationService.GetService(Viewer);
if (service != null && service.IsEnabled)
{
// (b) Сброс изменений в примечаниях в поток.
service.Store.Flush();
// (c) Выключение примечаний.
service.Disable();
// (d) Зарытие потока.
AnnotationStream.Close();
}
}

// The stream that we will store annotations in.
Stream AnnotationStream;
}[/code]
Откомпилируйте и запустите приложение. Когда Вы выделите текст в компоненте FlowDocumentPageViewer, кнопки на понели инструментов автоматически активизируются. Нажатие на "Add Text" и "Add Ink" будет вызывать создание StickyNote в документе. Примечания будут храниться в файле "annotations.xml" в CWD. Если Вы перезапустите приложение, примечания отоброзятся в документе снова.

ПРИМЕЧАНИЕ: автоматическое включение/отключение кнопок управления происходит только в случае, если кнопки расположены внутри панели инструментов. Причниной этого является то, что ToolBar динамически изменяет свойство CommandTarget дочерних элементов панели, которое основано на фокусе приложения. При использовании элемента ToolBar, Вы явно устанавливаете свойство CommandTarget="Viewer", т. е. фокусируете на программе просмотра.

Давайте рассмотрим программный код более подробно. В процедуре OnLoaded Мы сначала инициализируем поток (Stream), в который будет загружать и сохраняться примечания. Приложение управляет потоком (может его открывать, закрывать, обеспечивать права доступа и безопасность)последовательно записывая в него содержимое примечания. Также приложение предоставляет отдельный поток каждому комментируемому документу. Я скоро подготовлю несколько специальных примеров на эту тему, но запомните, что Вы не сможете использовать поток примечаний, созданных для DocumentA, когда просматриваете или комментируете DocumentB.

Теперь, когда есть поток, инициализируем службу AnnotationService для программы просмотра,в которой мы хотим включить примечания. Через этот сервис происходят все действия. Необходимо учитывать, что для каждой программы может быть только одна служба, а для документа - только один элемент AnnotationStore. Этот элемент управляет сохранением примечания на диск. Встроенным методом является XmlStreamStore, который читает и записывает данные из потока. В заключительном этапе Мы подключаем службу AnnotationService к нашему потоку.

В обработчике событий UnLoaded мы должны явным образом сбросить все изменения, созраненные в потоке. Затем выключаем сервис AnnotationService. И в конце, пока это в наших возможностях, закрываем поток.

Вот и все. Теперь Мы можем создавать примечания StickyNote в FlowDocument. Следующий код включает примечания, выделяет текст (написан на xaml):

Добавим секцию Grid.Resources, чтобы определить стиль отображения кнопок Highlight.

[code]<Grid.Resources>
<Style
x:Key="HighlightColorButtonStyle"
TargetType="{x:Type Button}" >
<Setter Property="Width" Value="20" />
</Style>
</Grid.Resources>[/code]
Добавьте этот GroupBox на ToolBar:

[code]<!-Выделенные операции -->
<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>[/code]

Все написанное является маленькой частью кода и пример на XAML, описывающий интерфейс пользователя, с помощью которого Вы сможете добавлять Highlights и StickyNotes во все документы FlowDocuments. Код и интерфейс пользователя работают таким же образом, что и другие программы просмотра, рассмотренные ранее.

ПРИМЕЧАНИЕ: Данный продукт является CTP-версией, поэтому возможны его изменения в будущем.

Источник: http://blogs.msdn.com/mehlhorn/
Перевод: RLV