OpenNETCF Mobile Ink Library Technical Overview

August 11, 2007 — Leave a comment

With the recent release of the Mobile Ink Library for Windows Mobile 6, some people are probably thinking ‘well what can I use that for’.  In the next few posts I’ll be going over some technical information and some possible uses for inking on the Windows Mobile 6 platform.


Windows Mobile 6 Inking


In the latest release of Windows Mobile, there is a new API called Windows Mobile Ink.  What is Windows Mobile Ink?  Where does it come from? Why do you need it? Well, basically Windows Mobile Ink is a new Inking API only available for the Windows Mobile 6 platform called WISP Lite.  It is based on Windows Inking Services Platform (WISP) for the Tablet PC


Desktop developers have managed classes available under the Microsoft.Ink namespace to allow them to develop managed applications to take advantage of ‘inking’ features available on Tablet PC.  A recent example for the desktop is using inking is ‘Ink-Enabling a SideBar Gadget‘  (This article does not deal with the desktop so I’ll leave it up to the user to search the many articles available on inking on the Tablet PC) 


The Windows Mobile 6 SDK contains some examples of using WISP Lite with native code.  Unfortunately if you are a managed developer, there are no managed classes available for your .NET Compact Framework applications.  The Mobile Ink Library addresses this issue and provides a library of classes that wrap the COM interfaces and the controls that are available on the Windows Mobile 6 platform.


Differences from the Desktop and Device


The Mobile Ink Library and WISP Lite allows a developer to add inking functionality to their Windows Mobile application.  WISP Lite (as the name implies) is a ‘lighter’ version or a subset of WISP available on the desktop.  For the managed desktop developer, there is the Microsoft.Ink namespace which provides inking capabilities in your .NET Framework application.  For the native developer there is also a COM API available to add inking capabilities to a native application. 


Currently for inking capabilities on the Windows Mobile 6 platform there are only COM interfaces and a ‘windowed control’ named InkCanvas available to native developers.  Managed developers using .NET Compact Framework don’t have any managed classes available but can wrap the COM interfaces and the InkCanvas control using version 2 of .NET Compact Framework.  The Mobile Ink Library has already done this and is available under the OpenNETCF.WindowsMobile.Ink namespace.  This gives the managed developer the ability to take advantage of this new API available. 


Both the desktop and the Windows Mobile versions of inking APIs allows the developer to save the ink in a format called Ink Serialized Format or ISF.  The ISF data output, which can be saved as Base64 or Binary, is compatible on both the desktop and mobile device.  If you try to open an ISF stream on mobile device that was saved on the desktop, the mobile device will ignore any properties in the stream that are not supported on Windows Mobile but still preserve the properties when saved again.  See this page for more details on the differences between the desktop and device.


COM Interfaces


There are various COM interfaces available for Windows Mobile Ink and for a details on using it with native code see ‘Using the Automation Library with Windows Mobile Ink‘.  The Mobile Ink Library wraps the appropriate interfaces to allow a managed developer to ink enable a .NETCF application.  Two interfaces that are primarily used and will be covering next are IInkDisp and IInkOverlay.


IInkOverlay


An IInkOverlay object is used to attach to a window (or control) using the IInkOverlay.hWnd property.  When you ‘attach’ a window to an IInkOverlay object, the window becomes ‘ink enabled’ and allows the collection of ink data. 


IInkOverlay also allows you to change the size, shape and color of the ink using the IInkOverlay.DefaultDrawingAttributes property.  The following example changes the size of the pen width using a TrackBar.Value property.


An example use of IInkOverlay is attaching it to a PictureBox and adding ink notes to an image.  The following code sample uses the OpenNETCF.WindowsMobile.Ink.InkOverlay class to achieve this:


To change the editing mode of the InkOverlay object the EditingMode property can be set with one of the following values:


IInkOverlay exposes a property called Ink which gets or sets the IInkDisp object that is associated with the IInkOverlay object.


IInkDisp


IInkDisp is responsible for collecting the ink strokes from a user.  It also has the ability to Save() and Load() the ink strokes collected by an IInkDisp.  To create an instance of IInkDisp, use OpenNETCF.WindowsMobile.Ink.InkDisp class has one static method called CreateInstance().  Usually you will want to create a new IInkDisp when you want to clear existing ink in an IInkOverlay.Ink.  An example of this is:


Note, to set the IInkOverlay.Ink property, you must first set IInkOverlay.Enabled to false and then once you set the IInkOverlay.Ink property set the IInkOverlay.Enabled back to true. 


When saving the ink strokes, the Save() method returns a byte[]  and there are four possible options defined in OpenNETCF.WindowsMobile.Ink.InkPersistenceFormat:



  • InkSerializedFormat – The ink data using ISF.  This is the most compact representation of ink data.
  • Base64InkSerializedFormat – The ink data using ISF and Base64 encoded.
  • Gif – The ink data in Graphics Interchange Format (Gif)
  • Base64Gif – The ink data Graphics Interchange Format (Gif) and Base64 encoded

These options allow the developer to save in various formats depending on their application requirements.  For example, if you are emailing the collected ink, the receiver may not be able to render the ISF format so you will probably want to send it as a Gif image attached to the email.


IInkDisp has a property call ExtendedProperties which allows the developer to save custom data within the ink data.  For example, using ExtendedProperties you can ’embedded’ some data to know when the ink data was last saved.  One caveat is ExtendedProperties are only persisted when saving as either InkSerializedFormat or Base64InkSerializedFormat so if you save as a Gif or Base64Gif, this data will be lost.


That summarizes IInkOverlay and IInkDisp which are probably the two main classes needed for inking.  I’ll leave it up to the reader to explore some of the other methods and properties available in these interfaces and some of the other interfaces available.


InkCanvas Control


The InkCanvas control is a windowed control and allows the developer to avoid using the COM Interfaces for inking in their application.  In addition to the COM Interfaces wrapped by Mobile Ink Library, the library also includes a managed wrapper appropriately called InkCanvas (found under OpenNETCF.WindowsMobile.Ink.InkCanvas). 


InkCanvas simplifies capturing ink within your application.  It uses windows messages to request operations and notify the user of any changes like adding or deleting ink.  If using the IInkDisp COM object is desired,  the OpenNETCF.WindowsMobile.Ink.InkCanvas.Ink property can be used.  InkCanvas also has the following properties which may be useful



  • Mode – Gets or sets the editing mode
  • Ink – Gets the IInkDisp object
  • BackColor – Gets or Sets the background color
  • ZoomLevel – Gets or sets the zoom level
  • CanvasSize – Gets or sets the canvas size
  • RecognizedText – Gets the recognized ink as text
  • PenStyle – Gets or sets the style of pen to use for example pen or highlighter

There are also various methods available in the InkCanvas control which are pretty self explanatory so I’ll leave it up to the reader to explore. 


Ink Recognition


One of the great benefits of the Windows Mobile Ink API is the ability to convert the ink data to a text string or ink recognition. 


The following code sample will convert ink data to a text string using the COM objects:


If you use the InkCanvas control the RecognizedText property can be used.  Internally the InkCanvas control does the following to recognize the ink data:


Essentially both methods would produce the same results for the same ink data.


Conclusion


The OpenNETCF Mobile Ink Library is a wrapper to the Windows Mobile Ink API available for Windows Mobile 6.  OpenNETCF Mobile Ink Library takes the pain away from the developer from having to wrap the native COM Interfaces and controls to be able to use this new API within a .NET Compact Framework application.


Now that you have an overview of what was wrapped in OpenNETCF Mobile Ink Library and how to use it, next we look at some of the samples that are included in the library …

No Comments

Be the first to start the conversation.

Leave a Reply