Support for user controls with the LEADTOOLS Annotation Automation.
The IAnnAutomationControl lets you easily use any control you choose with LEADTOOLS Annotation Automation. By default, the automation framework provides supports for using a LEADTOOLS Leadtools.WinForms.RasterImageViewer control as the surface where the automation is used. This is accomplished by creating the AnnAutomation object using the AnnAutomation(AnnAutomationManager, RasterImageViewer) method and optionally, using AnnAutomation.AttachViewer and AnnAutomation.DetachViewer.
To perform automation, the toolkit must interact with the control in different ways, for example, obtain information about the control size and resolution, subscribe to the various mouse and keyboard events for user-interface integration, invalidate all or portions of the control surface for re-painting to draw the annotation objects and translate values between annotation and client coordinates.
When the above mode is used, LEADTOOLS will create an internal helper class that implements IAnnAutomationControl and provides translation between the methods/properties/events of the interface and those of Leadtools.WinForms.RasterImageViewer.
To instead use automation on your own custom control, you must create a class that implements IAnnAutomationControl and pass an instance of this class to AnnAutomation(AnnAutomationManager, IAnnAutomationControl) and optionally to AnnAutomation.Attach and AnnAutomation.Detach if more advanced functionality is required.
IAnnAutomationControl is designed so that you can easily use it to create an automation control from a class derived from the standard System.Windows.Forms.Control class. The names of the methods/properties/events are such that in a lot of cases, you do not need to provide an implementation to them, instead, they will be wired in automatically as described in the table below. The other members that are not usually defined by System.Windows.Forms.Control have the prefix "Automation" in their names to easily distinguish them from the standard members.
To use IAnnAutomationControl, you must implement all of the following members:
Member | Description |
---|---|
IAnnAutomationControl.AutomationControl | The System.Windows.Forms.Control to use for automation. This value cannot be a null reference (Nothing in Visual Basic). The automation object will use this value to add/remove child controls, invalidate its surface and use it many other ways. |
Value that indicates whether the automation is enabled. When the value of this property is true, automation is enabled and when the user clicks and drags with the mouse or press keys on the keyboard, the automation object will process these events and perform the necessary actions (such as drawing new annotations objects or moving existing ones). If the value of this property is false, automation is disabled and the automation object will not process these events. You can use this property to easily enable/disable automation on this object from your user interface. If you decide to always enable automation, simply return true. You must trigger the IAnnAutomationControl.AutomationEnabledChanged event when the value of this property is changed. |
|
An event of type System.EventHandler that must trigger whenever the value of AutomationEnabled is changed. If your implementation does require enabling/disabling the automation, then you do not have to trigger this event from your code. When this event triggers, the automation object will query the IAnnAutomationControl.AutomationEnabled property and consequently starts or stops hooking the mouse and keyboard events. |
|
The Leadtools.RasterImage instance this automation will use when the user performs actions that will change the image being annotated. This is only used when the following methods are called: AnnEncryptObject.Apply, AnnRedactionObject.Realize and AnnRedactionObject.Restore. If you do not need to support these methods (By not supported encrypt and redaction objects, for example if you are implementing a system where only rectangles, rulers, images, audio and other objects like that are supported), then you can safely return a null reference (Nothing in Visual Basic) from your implementation of IAnnAutomationControl. |
|
The width of the image being annotated in pixels. Usually you will return the width of the image you are using in AutomationRasterImage (RasterImage.ImageWidth), however, since you do not need to implement that property and can safely return null in some case, you must always manually implement AutomationImageWidth to return the image width in pixels. In this case, the width of the virtual image you will be using in automation. You must trigger the IAnnAutomationControl.AutomationImageChanged event when the value of this property is changed. |
|
The height of the image being annotated in pixels. Usually you will return the height of the image you are using in AutomationRasterImage (RasterImage.ImageHeight), however, since you do not need to implement that property and can safely return null in some case, you must always manually implement AutomationImageHeight to return the image height in pixels. In this case, the height of the virtual image you will be using in automation. You must trigger the IAnnAutomationControl.AutomationImageChanged event when the value of this property is changed. |
|
The horizontal resolution of the image being annotated in dots per inch. Usually you will return the resolution of the image you are using in AutomationRasterImage (RasterImage.XResolution), however, since you do not need to implement that property and can safely return null in some case, you must always manually implement AutomationImageDpiX to return the resolution in dots per inch. In this case, the resolution of the virtual image you will be using in automation or simply 0 to use the current screen resolution. You must trigger the IAnnAutomationControl.AutomationImageChanged event when the value of this property is changed. |
|
The vertical resolution of the image being annotated in dots per inch. Usually you will return the resolution of the image you are using in AutomationRasterImage (RasterImage.YResolution), however, since you do not need to implement that property and can safely return null in some case, you must always manually implement AutomationImageDpiY to return the resolution in dots per inch. In this case, the resolution of the virtual image you will be using in automation or simply 0 to use the current screen resolution. You must trigger the IAnnAutomationControl.AutomationImageChanged event when the value of this property is changed. |
|
An event of type System.EventHandler that must trigger whenever the properties of the image being automated is changed. If you are using a Leadtools.RasterImage object, then you trigger this event whenever the RasterImage.Changed event occurs. Note that this event should occur when the image physical properties has changed, for example, its width/height or resolution or when a new image is set in your control (if supported) and not when the pixel data of the image has changed which only requires a re-paint. For these changes, use the IAnnAutomationControl.AutomationPaint event. If your requirement does not have an image that will be changed while being automated, then you do not have to trigger this event. When this event triggers, the automation object will query the IAnnAutomationControl.AutomationImageWidth, IAnnAutomationControl.AutomationImageHeightIAnnAutomationControl.AutomationImageDpiX and IAnnAutomationControl.AutomationImageDpiY properties to recalculate the size of the container. |
|
a value indicating whether the automation object should pay consideration to the image and control resolution when drawing annotation objects. The automation uses the resolution when translation values to pixels, for example, when calculating point size of a font. Also, objects such as rulers will use the resolution to correctly display the value in device independent coordinates such as inches and millimeters. If the value of this property is true, then the automation will use AutomationImageDpiX, AutomationImageDpiY, AutomationDpiX and AutomationDpiY to when calculating these values and ensure the result value on screen is accurate. If the value of this property is false, then the automation will not use any of these values and the calculations will be done using a default value of 96 dots per inch. You must trigger the IAnnAutomationControl.AutomationUseDpiChanged event when the value of this property is changed. |
|
An event of type System.EventHandler that must trigger whenever the value of IAnnAutomationControl.AutomationUseDpi is changed. When this event triggers, the automation object will query this property to re-calculate the values needed. |
|
The horizontal resolution of the control being annotated in dots per inch. Usually you will return the resolution of the control you are using in IAnnAutomationControl by obtaining it in a standard way in Windows.Forms. For example, using System.Windows.Forms.Control.CreateGraphics and returning Graphics.DpiX of the result object or simply 0 to use the current screen resolution. |
|
The vertical resolution of the control being annotated in dots per inch. Usually you will return the resolution of the control you are using in IAnnAutomationControl by obtaining it in a standard way in Windows.Forms. For example, using System.Windows.Forms.Control.CreateGraphics and returning Graphics.DpiY of the result object or simply 0 to use the current screen resolution. |
|
A System.Drawing.Drawing2D.Matrix object that represents the current transformation for the annotations objects. This value cannot be a null reference (Nothing in Visual Basic) and the object returned will be owned by the automation object and will be disposed internally when it is no longer needed. You must set this matrix with the current scroll and zoom values of your control and set up your application to either create or return a new instance of this matrix on demand whenever this property is called. For more explanation, refer to the example source code of this class. If you will not support scrolling or zooming in your application, then simply return an identity matrix (a new System.Drawing.Drawing2D.Matrix object). You must trigger the IAnnAutomationControl.AutomationTransformChanged when the value of this property is changed. |
|
An event of type System.EventHandler that must trigger whenever the value of IAnnAutomationControl.AutomationTransform is changed - that is, when your control is scrolled or zoomed in or out. When this event is triggered, the automation control will query the value of this property and might re-paint the annotations objects. Notice that you must trigger this event with the size of the control is changed so the automation object will use the new value of IAnnAutomationControl.ClientRectangle. |
|
An event of type System.Windows.Forms.PaintEventArgs that must trigger whenever the surface of the control is invalidated. The automation control will then automatically use the values of the event arguments to draw the annotations objects. In most cases, you simply have to trigger this event in your control System.Windows.Forms.Control.Paint event or System.Windows.Forms.Control.OnPaint method and pass the same arguments (of type System.Windows.Forms.PaintEventArgs) to IAnnAutomationControl.AutomationPaint. |
|
A method that will be called whenever AnnAutomation.Attach is called. You can add code to this method to handle any necessary code needed. |
|
A method that will be called whenever AnnAutomation.Detach is called. You can add code to this method to handle any necessary code needed. |
|
A mathod that will be called when the automation needs to re-paint the control. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this method (since the default System.Windows.Forms.Control.Invalidate will be used). If you have custom implementation, then simply invalidate your control surface when this method is called. |
|
A method that will be called when the automation needs to transform a point from screen to client coordinates. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this method (since the default System.Windows.Forms.Control.PointToClient will be used). |
|
A method that will be called when the automation needs to transform a point from client to screen coordinates. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this method (since the default System.Windows.Forms.Control.PointToScreen will be used). |
|
A method that will be called when the automation needs to transform a rectangle from client to screen coordinates. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this method (since the default System.Windows.Forms.Control.RectangleToScreen will be used). |
|
A rectangle that represents the client area of the control. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this property (since the default System.Windows.Forms.Control.ClientRectangle will be used). However, you must trigger the IAnnAutomationControl.AutomationTransformChanged event with the value of the client rectangle is changed, in most cases, by calling IAnnAutomationControl.AutomationTransformChanged from your System.Windows.Forms.Control.SizeChanged event or System.Windows.Forms.Control.OnSizeChanged method. |
|
Gets or sets the cursor to be used in the control. The automation will use many different cursors depending on current operation (drawing new annotations, moving existing annotations, etc). If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this property (since the default System.Windows.Forms.Control.Cursor will be used) |
|
An event of type System.Windows.Forms.MouseEventHandler that must trigger when the mouse is pressed on the control. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this event (since the default System.Windows.Forms.Control.MouseDown will be used) |
|
An event of type System.Windows.Forms.MouseEventHandler that must trigger when the mouse is moved on the surface of the control. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this event (since the default System.Windows.Forms.Control.MouseMove will be used) |
|
An event of type System.Windows.Forms.MouseEventHandler that must trigger when the mouse is depressed on the surface of the control. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this event (since the default System.Windows.Forms.Control.MouseUp will be used) |
|
An event of type System.EventHandler that must trigger when the mouse is double clicked on the surface of the control. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this event (since the default System.Windows.Forms.Control.DoubleClick will be used) |
|
An event of type System.Windows.Forms.KeyEventHandler that must trigger when a key is pressed when your control has focus. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this event (since the default System.Windows.Forms.Control.KeyDown will be used) |
|
An event of type System.EventHandler that must trigger when your control receives the focus. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this event (since the default System.Windows.Forms.Control.GotFocus will be used) |
|
An event of type System.EventHandler that must trigger when your control loses the focus. If your control is derived from the standard System.Windows.Forms.Control, then you do not need to implement this event (since the default System.Windows.Forms.Control.LostFocus will be used) |
This example will use IAnnAutomationControl to use LEADTOOLS Annotations Automation on a custom control that uses standard System.Drawing.Image with scrolling and zooming.