This documentation is archived and is not being maintained.

Creating an Ink Input Control

You can create a custom control that dynamically and statically renders ink. That is, render ink as a user draws a stroke, causing the ink to appear to "flow" from the tablet pen, and display ink after it is added to the control, either via the tablet pen, pasted from the Clipboard, or loaded from a file. To dynamically render ink, your control must use a DynamicRenderer. To statically render ink, you must override the stylus event methods (OnStylusDown, OnStylusMove, and OnStylusUp) to collect StylusPoint data, create strokes, and add them to an InkPresenter (which renders the ink on the control).

This topic contains the following subsections:

To create a control that collects and manages ink strokes do the following:

  1. Derive a class from Control or one of the classes derived from Control, such as Label.

    No code example is currently available or this language may not be supported.
  2. Add an InkPresenter to the class and set the Content property to the new InkPresenter.

    No code example is currently available or this language may not be supported.
  3. Attach the RootVisual of the DynamicRenderer to the InkPresenter by calling the AttachVisuals method, and add the DynamicRenderer to the StylusPlugIns collection. This allows the InkPresenter to display the ink as the stylus point data is collected by your control.

    No code example is currently available or this language may not be supported.
  4. Override the OnStylusDown method. In this method, capture the stylus with a call to Capture. By capturing the stylus, your control will to continue to receive StylusMove and StylusUp events even if the stylus leaves the control's boundaries. This is not strictly mandatory, but almost always desired for a good user experience. Create a new StylusPointCollection to gather StylusPoint data. Finally, add the initial set of StylusPoint data to the StylusPointCollection.

    No code example is currently available or this language may not be supported.
  5. Override the OnStylusMove method and add the StylusPoint data to the StylusPointCollection object that you created earlier.

    No code example is currently available or this language may not be supported.
  6. Override the OnStylusUp method and create a new Stroke with the StylusPointCollection data. Add the new Stroke you created to the Strokes collection of the InkPresenter and release stylus capture.

    No code example is currently available or this language may not be supported.

If you add the preceding control to your application, run it, and use the mouse as an input device, you will notice that the strokes are not persisted. To persist the strokes when the mouse is used as the input device do the following:

  1. Override the OnMouseLeftButtonDown and create a new StylusPointCollection Get the position of the mouse when the event occurred and create a StylusPoint using the point data and add the StylusPoint to the StylusPointCollection.

    No code example is currently available or this language may not be supported.
  2. Override the OnMouseMove method. Get the position of the mouse when the event occurred and create a StylusPoint using the point data. Add the StylusPoint to the StylusPointCollection object that you created earlier.

    No code example is currently available or this language may not be supported.
  3. Override the OnMouseLeftButtonUp method. Create a new Stroke with the StylusPointCollection data, and add the new Stroke you created to the Strokes collection of the InkPresenter.

    No code example is currently available or this language may not be supported.

The following example is a custom control that collects ink when the user uses either the mouse or the pen.

No code example is currently available or this language may not be supported.

Like the InkCanvas, your custom control can have custom StylusPlugIn and additional DynamicRenderer objects. Add these to the StylusPlugIns collection. The order of the StylusPlugIn objects in the StylusPlugInCollection affects the appearance of the ink when it is rendered. Suppose you have a DynamicRenderer called dynamicRenderer and a custom StylusPlugIn called translatePlugin that offsets the ink from the tablet pen. If translatePlugin is the first StylusPlugIn in the StylusPlugInCollection, and dynamicRenderer is the second, the ink that "flows" will be offset as the user moves the pen. If dynamicRenderer is first, and translatePlugin is second, the ink will not be offset until the user lifts the pen.

You can create a control that collects and renders ink by overriding the stylus event methods. By creating your own control, deriving your own StylusPlugIn classes, and inserting them the into StylusPlugInCollection, you can implement virtually any behavior imaginable with digital ink. You have access to the StylusPoint data as it is generated, giving you the opportunity to customize Stylus input and render it on the screen as appropriate for your application. Because you have such low-level access to the StylusPoint data, you can implement ink collection and render it with optimal performance for your application.

Show: