InkPresenter
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Implements a rectangular surface that displays ink strokes and can be a child, sibling, or parent of other objects.
<InkPresenter ...>
oneOrMoreUIElements
</InkPresenter ...>
XAML Values
Value |
Description |
|---|---|
oneOrMoreUIElements |
One or more of the following object elements that derive from UIElement: Border (Silverlight 2), Canvas, Ellipse, Glyphs, Grid (Silverlight 2), Image, InkPresenter, Line, MediaElement, PasswordBox (Silverlight 2), Path, Polygon, Polyline, Rectangle, Shape, StackPanel (Silverlight 2), TextBlock, TextBox (Silverlight 2). Object elements defined here become members of the Children collection when scripting accesses the Children property at run time. |
Methods
AddEventListener, CaptureMouse, Equals, FindName (DependencyObject), GetHost, GetParent, GetValue, ReleaseMouseCapture, RemoveEventListener, SetValue
Properties
Background (Elements), Canvas.Left, Canvas.Top, Canvas.ZIndex, Children (Panel), Clip, Cursor, Effect (Silverlight 3), Grid.Column (Silverlight 2), Grid.ColumnSpan (Silverlight 2), Grid.Row (Silverlight 2), Grid.RowSpan (Silverlight 2), Height (UIElement), HorizontalAlignment (Silverlight 2), IsHitTestVisible, IsItemsHost (Silverlight 3), Language (Silverlight 2), Margin (Silverlight 2), MaxHeight (Silverlight 2), MaxWidth (Silverlight 2), MinHeight (Silverlight 2), MinWidth (Silverlight 2), Name (DependencyObject), Opacity (UIElement), OpacityMask, Projection (Silverlight 3), RenderTransform, RenderTransformOrigin, Resources, Style (Silverlight 2), Strokes, Tag, TextOptions.TextHintingMode (Silverlight 3), Triggers, UseLayoutRounding (Silverlight 2), VerticalAlignment (Silverlight 2), Visibility, Width (UIElement)
Events
Loaded, MouseEnter, MouseLeave, MouseLeftButtonDown, MouseLeftButtonUp, MouseMove, MouseWheel (Silverlight 3)
Remarks
InkPresenter is a derived object of Canvas. In particular, it inherits two properties that relate to presentation: Background and Children. The Background value for an InkPresenter object is applied behind any strokes that are presented on the surface.
Children is the content property for InkPresenter, which is why it is referenced as the oneOrMoreUIElements placeholder in the XAML syntax above. Because the primary purpose of InkPresenter is to display strokes, it is more common to set Children for a Canvas object rather than to specify Children UI elements for an InkPresenter. However, setting Children on an InkPresenter might be useful for certain scenarios such as providing a visual guide, a watermark, controls within the ink capture area, etc.
Children values for an InkPresenter render on the InkPresenter surface just as they do on a Canvas. However, the collection of strokes is stored separately in the Strokes property. By default, a Canvas will draw Children elements in the order that they are declared for purposes of overlaps in rendering (for example, the last element declared will draw on top). However, you can adjust this order by setting Canvas.ZIndex property values on the child elements.
All Children items draw over the Background. All Strokes draw over both Children and Background, and you cannot adjust Strokes with Canvas.ZIndex. Therefore, if you want any content to always remain on top of strokes, you should declare that content in a separate Canvas that overlays the InkPresenter, rather than setting the Children property of the InkPresenter in script or as direct element content in XAML.
Example
The following example code shows basic techniques for capturing input on an InkPresenter surface and using the input to create strokes to display.
var agCtrl;
var inkPresenter; // Corresponds to InkPresenter element in XAML.
var newStroke = null; // The Stroke variable to use in mouse handlers.
// Specify DrawingAttributes variables.
var daWidth = 2;
var daHeight = 2;
var daColor = "Black";
var daOutlineColor = "Black";
function root_Loaded(sender, args)
{
// Get the HTML object that contains the Silverlight plug-in.
agCtrl = sender.GetHost();
inkPresenter = sender.findname("inkPresenterElement");
}
// Capture mouse movement when the left button is pressed, and create the stroke.
function InkPresenterMouseDown(sender,args)
{
inkPresenter.CaptureMouse();
newStroke = agCtrl.content.createFromXaml('<Stroke/>');
var da = agCtrl.content.CreateFromXaml('<DrawingAttributes/>');
newStroke.DrawingAttributes = da;
// Set the drawing attributes properties.
newStroke.DrawingAttributes.Width = daWidth;
newStroke.DrawingAttributes.Height = daHeight;
newStroke.DrawingAttributes.Color = daColor;
newStroke.DrawingAttributes.OutlineColor = daOutlineColor;
newStroke.StylusPoints.AddStylusPoints(args.GetStylusPoints(inkPresenter));
inkPresenter.Strokes.Add(newStroke);
}
// Add the new points to the Stroke.
function InkPresenterMouseMove(sender,args)
{
if (newStroke != null)
{
newStroke.StylusPoints.AddStylusPoints(args.GetStylusPoints(inkPresenter));
}
}
// Release the mouse button.
function InkPresenterMouseUp(sender,args)
{
newStroke = null;
inkPresenter.ReleaseMouseCapture();
}