Mobile Ink Jots 5: Control Issues

 

David Hale
Microsoft

December, 2004

Applies to:
Microsoft® Windows® XP Tablet PC Edition 2005
Microsoft Windows XP Tablet PC Development Kit 1.7

Summary: This column examines the two controls that are part of the Windows XP Tablet PC Edition Development Kit 1.7, as well as two commercially-available controls made specifically for the tablet PC Platform. We also illustrate how to extend the Tablet PC controls, so you can add additional functionality. Example code is written in C#. (9 printed pages)

Contents
Introduction
Extending the Span of Your Control
Take Control with NetAdvantage from InfraGistics
Take a Quick Note with Agilix InfiNotes
Conclusion

Introduction

We are casting a wide net in this month's Mobile Ink Jots column, where we reveal a grab-bag of information about how controls can make your life easier as a Tablet PC developer. We look at some fantastic commercial controls that have been developed especially for Tablet PC. We also, by way of reminder, look at how you can extend the controls provided by the Tablet PC Platform to meet your needs.

A control is "a reusable piece of software functionality that (usually) provides a visible interface." Generally speaking, it's that part about providing a visible interface that distinguishes a control from a component. Every control is a component, but the converse is not true.

Note   For an eloquent overview of the evolution of controls from early Windows controls to those used in the .NET Framework—it's the source for the definition of a control in the previous paragraph—see David Platt's April 2002 MSDN Magazine article Developing Compelling User Controls that Target Forms in the .NET Framework.

The Tablet PC platform team provided developers with a couple of useful controls in version one. The InkEdit control, which predates the in-place Text Input Panel that shipped in Windows XP Tablet PC Edition 2005, extends RichTextBox functionality by adding the ability to write with a pen and have the ink recognized and inserted. The InkPicture control extends the PictureBox control of the .NET Framework, allowing for images to be marked-up with ink.

Extending the Span of Your Control

Let's take a look at how you can extend one of these Tablet PC platform controls to fit your need. In this example, we extend the standard InkEdit control to provide some additional functionality.

First, some background about the problem our control will solve. In order to create an application dictionary, it is necessary to set the WordList property of a RecognizerContext object. However, the InkEdit control does not expose the RecognizerContext object, so it is not possible to directly set the WordList property of the InkEdit control's RecognizerContext object. To use an application dictionary with an InkEdit control, you must

  1. Take the Stroke objects out of the InkEdit control.
  2. Pass the Stroke objects to a new RecognizerContext object with the WordList property set to a word list containing the application dictionary.
  3. Store the results from this RecognizerContext object.
  4. Pass the results back to the InkEdit control.

While the ever-useful Tablet PC SDK documentation does provide a work around for this lack of platform functionality, it might be useful to wrap this workaround in a custom control that allows you to simply set a WordList property. I have done just that in a sample project I wrote to come up with the code for this installment of Mobile Ink Jots.

Inside the project I create a class called InkEditWordList that inherits from InkEdit.

public class InkEditWordList : Microsoft.Ink.InkEdit

The class contains some member fields used to enable the word list:

private Microsoft.Ink.RecognizerContext recocontext;
private Microsoft.Ink.WordList wordlist;
//used to control whether or not the in-place Input Panel appears.
private Microsoft.Ink.PenInputPanel peninputpanel;

private bool iptipEnabled;
private int wlSelStart;
private int wlSelLen;

In the constructor for the class, I assign a delegate to handle the Recognition event for the control and set the iptipEnabled field to false. This field holds a value that indicates whether or not the in-place Input Panel appears when the control receives focus. I enable the user of my control to set whether or not to use Input Panel by implementing a new property, InputPanelEnabled. The default value is false.

public InkEditWordList()
  {
    InitializeComponent();

    // Handle the regular recognition event for the control.
   //This is where we will hook up the RecognizerContext.
    this.Recognition +=new InkEditRecognitionEventHandler(InkEditPhraseList_Recognition);    
  }

As instructed in the workaround topic, in the handler for the first Recognition event, I set some information about where the selection begins and ends, then copy the strokes from the underlying InkEdit control's Ink object to the Strokes property on the RecognizerContext that I am using to leverage the WordList. Then I call BackgroundRecognizeWithAlternates to begin recognition.

Continuing with the workaround, I handle the RecognitionWithAlternates event by selecting the original recognition result, then replacing it with the best recognition alternate from the RecognizerContext and moving the insertion point to the end of the recognized text.

private void rc_RecognitionWithAlternates(object sender, RecognizerContextRecognitionWithAlternatesEventArgs e)
  {
    //Select the original recognition result.
    this.SelectionStart = selStart;
    this.SelectionLength = selLen;

    //Replace it with the coerced top string.
    this.SelectedText = e.Result.TopString;

    //Move the insertion point to the end of the control.
    this.SelectionStart = this.SelectionStart + e.Result.TopString.Length;
  }

The interesting part, for purposes of this column, is how I implement the public members that I expose on my control. The following code is the WordList property that allows the developer to set the word list used by the control or to clear the WordList property by passing in NULL.

public Ink.WordList WordList
  {
    get
    {
      return wordlist;
    }
    set
    {
         wordlist = value;

      if (wordlist == null)
      {
        //clear the wordlist, regardless of whether we're 
        //setting a new one.
        recocontext.Strokes = null;
        recocontext.Factoid = "DEFAULT";
        recocontext.RecognitionFlags = RecognitionModes.None;
      }
      else
      {
        recocontext.Strokes = null;
        recocontext.Factoid = "WORDLIST";
        recocontext.WordList = wordlist;
        recocontext.RecognitionFlags = RecognitionModes.Coerce;
      }
    }
  }

For completeness, here is the code that implements the InputPanelEnabled property.

public bool InputPanelEnabled
  {
    get
    {
      return iptipEnabled;
    }
    set
    {
      iptipEnabled = value;
      peninputpanel.AutoShow = iptipEnabled;
    }
  }

It is also worth noting that because I am accessing certain members of the underlying class that are not created until the class is fully instantiated (namely, the Recognizer object on the InkEdit from which I create the RecognizerContext), I have to create those objects in the OnHandleCreated event rather than the constructor for my control. I also disable the in-place Input Panel here.

protected override void OnHandleCreated(EventArgs e)
  {
    base.OnHandleCreated (e);

    wordlist = new Microsoft.Ink.WordList();

    // Create a recognizer context to attach the WordList to
    // and attach recognition event handler for it.
    recocontext = this.Recognizer.CreateRecognizerContext();
    recocontext.RecognitionWithAlternates +=new RecognizerContextRecognitionWithAlternatesEventHandler(rc_RecognitionWithAlternates);

    //Disable the in-place Input Panel on Windows XP Tablet PC Edition 2005.
    iptipEnabled = false;

    peninputpanel = new PenInputPanel(this);
    peninputpanel.AutoShow = iptipEnabled;
  }

So, now you have seen what is involved in customizing a control to fit your needs. Pretty simple, but still, it does take some work. For a more complete example of how to create a control, including design environment support, see the InkShortcut control sample in the Tablet PC Developer Center downloads section. There are also some great samples in the Tablet PC Development Kit, including how to create a UserControl with inking support that can run in the Internet Explorer application context. That means your ink control can run from the Web!

If you're like me, and you like to leave the details to the professionals, you may want to take a look at some of the control suites that are available from commercial vendors.

Take Control with NetAdvantage from InfraGistics

Scores of developers take advantage of a suite of controls available from InfraGistics called NetAdvantage 2004. NetAdvantage, based on their extremely rich Presentation Layer Framework, enables building a variety of types of applications.

Infragistics is a major publisher of reusable, presentation-layer development tools for Microsoft ASP.NET, Windows Forms, Tablet PC, and Component Object Model environments. To make it easier to deploy Tablet PC-based solutions, Infragistics developed the .WinInkProvider library for the Microsoft .NET Framework. The library adds to the already robust ink capabilities provided by Windows XP Tablet PC Edition through advanced support for freeform and masked ink text fields. Adding the ink provider library to traditional Windows Forms elements instantly adds ink support. The library provides support for native pen-based editing, an easy-to-use pop-up pen input panel for any text box, and a correction interface to adjust misinterpreted characters with ease.

Jason Beres, chief technology evangelist at Infragistics, says, "Adding ink support is surprisingly easy. The Tablet PC software development kit (SDK) has great native functionality. Ink enablement can be done with three lines of code. Infragistics builds on the solid base formed by the Tablet PC SDK to add advanced editing for complex elements like currencies and symbols." Thus, Infragistics makes it even faster and easier for ISVs to create compelling Tablet PC-based solutions that address customer needs.

Focusing in on the Tablet-specific functionality, the .WinInkProvider, you quickly see how InfraGistics has made it simple to make a NetAdvantage based application Tablet enabled. The Tablet features provide freeform or masked ink support for all Infragistics text-based editors, as well as their WinGrid, WinTree and WinScheduling features.

Take a Quick Note with Agilix InfiNotes

If you have been following along at home as the Tablet PC platform evolves, you know that the Tablet PC Development Kit provides a deep and extensible set of APIs. You are also acquainted with the fact that you can easily collect, save, and recognize ink.

Once you understand these fundamentals and it comes time to put it all together, you may have discovered that there is still quite a bit of work involved to do something interesting in your application. For instance, one thing that the Tablet PC platform team has heard from all types of developers is that while the platform is rock solid and easy to learn there are a few core scenarios that are too difficult to achieve. First among these scenarios is the need to re-create "Journal-like" note taking capability inside an application quickly and easily.

For example, say you have designed your program to be used by a home inspector as she goes through a house. You likely include one or more fields where the inspector can take free form notations as part of her inspection and save the notes along with the report. You want this note taking experience to be intuitive for the user. That is, the user must be able to do everything in the note that she could in Journal, such as changing pen sizes, colors and types, erasing ink, selecting ink, undoing ink, recognition, and the like.

To enable this happen, you can attach an InkCollector to a Panel on your Form, then create and wire up a toolbar that looks like Journal's. You have to write all the code to manage undo and redo, provide a correction user interface for recognized text, and all the other plumbing necessary to make the notes field a reality.

Luckily though, there now exists a dramatically easier way to add "full-fidelity" note-taking into your application. Agilix recently announced a preview of their new InfiNotes Note-taking Framework. In a word, InfiNotes enables you to achieve the notes scenario in your home inspector application by simply dragging and dropping a control onto your form and compiling.

In the rest of this month's column, let's examine exactly what InfiNotes provides and then write a quick application that exploits its functionality.

What is InfiNotes?

InfiNotes consists of a suite of managed controls based on the Windows XP Tablet PC Edition 2005 platform. The suite provides a range of managed objects and controls which offer several levels of note taking support. Each member of the suite is found in one of the following namespaces.

  • Agilix.Ink
  • Agilix.Ink.Command
  • Agilix.Ink.Dialogs
  • Agilix.Ink.Edit
  • Agilix.Ink.Element
  • Agilix.Ink.Note
  • Agilix.Ink.StylusMode

At the bottom of the stack is the RtsOverlay object. As the name implies, RtsOverlay derives from the new RealTimeStylus input APIs (RTS for short) that debuted in version 1.7 of the Tablet PC 2005 Development Kit. In simple terms, the RtsOverlay can be thought of as an RTS-based replacement for the InkOverlay object in the Tablet PC SDK. Like the InkOverlay, RtsOverlay implements lasso selection as well as both point and stroke erasing.

RtsOverlay also serves as the base for the next control in the stack, the Doodle control. Doodle builds on RtsOverlay, adding highlighting, moving, sizing, drag/drop, ink formatting and multi-level undo.

Next up the chain of controls sits the Note control, based on Doodle. Note adds support for stationery, inserting space, scrolling (infinite writing space), background ink recognition, search, and copy as text/convert to text (for export).

The only thing that separates the Note control from the Journal-like functionality we are looking for in our sample scenario is the familiar, easy-to-use user interface found in Journal for doing things like selecting pens, switching to erase mode, and the like. Fortunately, the folks at Agilix created a reusable Toolbar control that does this, and even attached it to a Note control to craft the ultra-useful NoteBox control.

The following table, adapted from the InfiNotes help file, lays out the differences in the controls in the suite.

Feature Doodle Note NoteBox
Ink collection X X X
Highlighting X X X
Lasso selection X X X
Eraser (stroke and pixel) X X X
Moving/Sizing X X X
Ink formatting X X X
Cut/Copy/Paste X X X
Drag/Drop X X X
Multilevel Undo/Redo X X X
Background Image X X X
Stationery X X
Insert Space X X
Scrolling (Infinite writing space) X X
Background ink recognition X X
Search X X
Copy as Text/Convert to Text (for export) X X
Embedded toolbar X
Note   You might want to use a single Toolbar to control multiple Note controls, so Agilix has provided the Toolbar as a stand alone control. Those guys thought of everything!

Where to Get InfiNotes

Two versions of the control exist. The Basic Edition, discussed in this article, is free to obtain and use! Go to http://www.infinotes.com to register and download it.

If you need more features, purchase InfiNotes Professional Edition from Agilix.

According to Agilix, the Professional Edition includes advanced concepts such as pagination, zooming, and more object manipulation. The professional edition also includes the ability to capture and annotate on top of documents created by other applications, the ability to combine computer text and ink on the same document, and the incorporation of drawing objects. InfiNotes Professional Edition also provides a more extensible architecture to support a greater variety of ink-enabled applications.

Conclusion

This month, you learned about the options available to you for creating and or using controls on the Tablet PC platform. You saw some details about the InfiNotes suite of controls from Agilix, learned about Infragistics control suite, and got introduced to how to bake your own controls. Now you are empowered. Get out there and take control!

Show: