Using the Ink Explorer

Stefan Wick
Mark Hopkins
Microsoft Corporation

February 2006

Applies to:
   Microsoft Windows XP Tablet PC Edition

Summary: The Ink Explorer is a sample application that provides access to all the properties of ink strokes for examination by the user. It is a very useful tool for understanding the architecture of the Microsoft Windows XP Tablet PC Edition implementation of digital ink. (5 printed pages)

Click here to download the sample code for this article.

What is the Ink Explorer?
Ink Explorer Functionality
Exploring Ink
The Source Code
Conclusion

Ink Explorer is a sample application that the Tablet PC team sometimes uses at conferences when discussing the architecture of digital ink in Microsoft Windows XP Tablet PC Edition. Ink Explorer is very useful for learning about how to use the ink APIs, containing good examples of the kind of code necessary to use in ink-enabled applications.

Ink Explorer has three control areas in its main window:

• An InkPicture
• A TreeView
• A ListView

Ink Explorer uses the InkPicture control to capture ink strokes for analysis. To modify the attributes of the strokes, click Pen Settings on the Tools menu.

The TreeView control displays the hierarchy of the Ink object and the strokes contained within it. This includes properties such as the DrawingAttributes and ExtendedProperties collection on a Stroke. This view gives a very nice conceptual picture of the Ink architecture.

The ListView displays information about the item currently selected in the TreeView. For example, if you click an individual stroke in the TreeView pane (Stroke_1, in the example screenshot in Figure 1), you see all of the packet data for that stroke. This is more fully explained in Exploring Ink, later in this article.

Figure 1. Screenshot of Ink Explorer. Note that TreeView, ListView, and InkPicture are labels on the screenshot. The labels do not appear in the sample application.

The menus provide access to the functions you would expect to find in an ink-enabled application, with a few notable exceptions. The View menu contains the Rotate command, which rotates the ink 45 degrees. The Tools menu contains the Divide Ink command, which copies all the strokes into the CustomStrokes of the parent Ink object. In addition to the main menu bar, there are context menus available in the TreeView pane, which are discussed in more detail in Exploring Ink, later in this article.

The real value of Ink Explorer comes from experimenting with ink. Use the following steps to become familiar with the tool.

1. Open Ink Explorer, either through Visual Studio or InkExplorer.NET.exe, located in the debug folder of the sample.
2. Notice that there is a Strokes collection object inside the Ink object. Draw some strokes on the InkPicture control. The TreeView control is updated each time you lift the pen to complete a stroke.
3. Click the plus sign (+) to expand Stroke_1 in the TreeView pane. Notice that the stroke contains a DrawingAttributes property.
4. Click the plus sign (+) to expand the DrawingAttributes property of Stroke_1. Notice that, in addition to the stroke having an ExtendedProperties property, the DrawingAttributes has its own ExtendedProperties property.
5. Right-click some of the elements in the TreeView to see their context menus. These menus illustrate the kind of operations you can perform on strokes. For example, if you right-click a Strokes collection in the Ink object, you can recognize the strokes as text by using either the US English or UK English recognizer.
6. Click some other elements in the TreeView and notice how the ListView changes to give you information relevant to the item you selected.
7. Click and right-click other elements in the TreeView and see what you can do. Notice how your actions affect the strokes and their attributes.

Try using different inking modes.

1. Remove any ink currently in the InkPicture control. Click the File menu and then click Clear.
2. Draw some new strokes in the InkPicture control.
3. Expand the Strokes node in the TreeView.
4. Click the Mode menu, and then click Select.
5. Circle the strokes you drew. When you lift the pen, notice that the ink becomes selected.
6. Drag the selected ink to a new location.
7. Click the Mode menu, and then click Stroke Erase.
8. Drag the eraser across one of the strokes. The entire stroke disappears. Notice that the stroke is also removed from the Strokes node of the TreeView.
9. Click the Mode menu, and then click Point Erase.
10. Drag the eraser across the middle of a stroke. Only the area where the eraser intersected the stroke is removed. Also, note that another stroke was added to the Strokes collection in the TreeView. Also note that the stroke's ID is 3 more than that of the last stroke. For more information about the numbering of Stroke objects in a Strokes collection, see Tablet 101 Column 3: Strokes and Recognition, in the MSDN Library.

One of the most important aspects of the ink experience for an end user is the look and feel of the ink. You achieve this through the DrawingAttributes object assigned to each Stroke. A DrawingAttributes object describes how any known set of ink is to be drawn. A DrawingAttributes object includes basic properties such as Color, Width, and PenTip. It can also encompass advanced parameters, such as variable transparency and Bezier smoothing, that can provide interesting effects or improve ink readability.

1. Click the plus sign (+) to expand Stroke_1 in the TreeView pane. Notice that the Stroke contains a DrawingAttributes property.
2. Right-click the DrawingAttributes and click Modify. The DrawingAttributes dialog opens.
3. Click Color, click the dropdown arrow to the right of the Color field, and select some color other than black.
4. Change the width property from 53 to 200.
5. Click OK.

Note what happens to the way the Stroke is rendered. You can use the DrawingAttributes to give instant and meaningful feedback to the user.

Ink Explorer renders a visual representation of an Ink object. This may lead you to some new solutions that you hadn't considered before. For example, notice how many different places there are to store ExtendedProperties. Using the various properties may give you some extraordinary results. Try the following experiment:

1. In Ink Explorer, click the File menu, and then click Clear.

2. Click the Mode menu, and then click Ink.

3. Draw some ink in the InkPicture control.

4. Completely expand the Strokes collection. Notice that there is an ExtendedProperties property on:

   • The Strokes collection.
   • Each individual Stroke.
   • Each DrawingAttributes property of each Stroke.

   That's a lot of places to store your own data!

5. Right-click the ExtendedProperties node for the first Stroke in your collection, and then click Add Property. Notice that the Guid field is already populated by Ink Explorer. Each extended property is a GUID/value pair.

6. In the Value field of the AddProperty TextBox type, This is an extended property.

7. Click OK.

8. Click the File menu, click Save As, and save the ink as an Ink Serialized Format (ISF) file.

9. Click the File menu, and then click Clear to remove all the ink.

10. Click the File menu, click Open, and open the file you just saved.

11. Click the ExtendedProperties node for the first Stroke in your collection. The ExtendedProperties data is still there. The system stored and retrieved the data with the ink.

Use the ExtendedProperties to hold many types of useful information that you can access through this API. Feel free to try things on your own. Experiment!

The source code included with the Ink Explorer sample provides an excellent opportunity to see how to access the attributes of the Ink class. The code is organized by window. There are individual C# source files for:

• The main window (MainForm.cs).
• The DrawingAttributes dialog (DrawingAttributesForm.cs).
• The ExtendedProperties dialog (AddPropertyForm.cs).

The most interesting code is in the MainForm.cs file. The Menu event handlers region begins on line 1075 and contains the event handlers for all the menu choices. Some of the more interesting event handlers include:

• miInkEM_Click, miSelectEM_Click, miStrokeEraseEM_Click, miPointEraseEM_Click
  Changes the input mode to various editing and eraser modes.
• miRecoLanguage_Click
  Does handwriting recognition. To fire this event, right-click Strokes in the TreeView, point to Get RecognitionResult, and then click either recognizer.
• miRotate_Click
  Rotates the Strokes collection 45 degrees to the left.
• miStrokeRotate_Click
  Rotates the stroke currently selected in the TreeView by 45 degrees.
• miAddProp_Click
  Adds extended properties.
• miModifyDA_Click, frm_StrokeDrawingAttributesChanged, miModifyStrokesDA_Click, frm_StrokesDrawingAttributesChanged
  Manages the changing DrawingAttributes of the pen, individual strokes, and the Strokes collection.

Additionally, there are more menu event handlers for you to explore. Also, be certain to look at the UpdateTreeView and UpdateListView methods. These methods do all the work to extract and display the information about the strokes, such as X and Y point information, drawing attributes, and so on.

The Ink Explorer is an excellent tool for learning about the architecture of the Windows XP Tablet PC Edition platform. You can experiment with ink and get a good visual representation of the effects of your changes.