VG.net Readme

Thank you for using VG.net!

This document contains notes for using VG.net. You can find additional tips and tricks for VG.net at the development blog: http://weblogs.asp.net/frank_hileman. The VG.net home page is www.vgdotnet.com.

1. Getting Started

Please see the VG.net Users Guide section titled "Getting Started". You will find a shortcut to the Users Guide on the Start Menu, under the folder VG.net.

Some sample code is installed by the regular VG.net installation. You will find a link to the sample code in your start menu, under VG.net X/Samples, where "X" is the main VG.net version number. Extra sample code is also provided. This is called the Extras package, and must be installed separately when using Visual Studio versions prior to 2012. With Visual Studio 2012, the Samples and Extras are both combined and installed with the regular installer, and can be found in a single zip file. There is a short cut to this zip file in the start menu.

Missing Toolbar buttons? Sometimes the toolbar buttons and context menu items for Visual Studio fail to install correctly. If you notice missing items, please open the Add/Remove Programs window in the Control Panel, find VG.net, click on the link called "Click here for support information", and click on the Repair button.

2. License Agreement

The end user license agreement can be found in the file EULA.rtf, found in the main VG.net installation folder. Please note that the file Prodige.Drawing.dll may be redistributed only by companies who have purchased a designer license. No other files may be redistributed.

3. Support

If you have purchased a VG.net Picture Designer license, you will receive support contact information in your email receipt. If you are using a Lite or evaluation version of the Picture Designer, there is no official support, but please send bug reports or comments to support at vgdotnet.com, or post a message on the VG.net discussion forums at www.vgdotnet.com/forums.

4. Version Numbers and Source Code Compatibility

The major VG.net version number indicates the corresponding compatible Visual Studio version:

• VG.net Versions 7.x support Visual Studio 2012
• Versions 6.x support Visual Studio 2010
• Versions 5.x support Visual Studio 2008
• Versions 4.x support Visual Studio 2005

As much as possible, VG.net APIs are source code compatible between 7.x, 6.x, and 5.x releases. In the future, enhancements made in 7.x versions will appear in version 6.x and 5.x releases. If you purchase a VG.net designer license, you receive setup files for 7.x, 6.x, and 5.x versions.

5. Visual Studio 2010 and 2012 Notes

If you install multiple versions of VG.net on the same computer, please select the correct version of Prodige.Drawing.dll for your project references. Normally the dll reference SpecificVersion property can be left false, but when using multiple versions of Visual Studio, the SpecificVersion property must be set to true, to ensure the correct dll version is used. Use a 7.x version of Prodige.Drawing.dll for Visual Studio 2012; use a 6.x version for Visual Studio 2010; use a 5.x version for Visual Studio 2008.

6. Upgrading and Incompatibility of .resx Files

When using Visual Studio 2003, .resx files produced for Forms and UserControls containing Pictures have data later versions of Visual Studio cannot process. To work around this problem, delete .resx files for Forms and UserControls containing Pictures. If the .resx files contain important information, such as bitmaps, repair them: delete elements in the xml containing a Location property for a Picture. These elements are type System.Drawing.Point, for example:

Design-Time Properties

Modifiers property: Use this property, under “Design,” to make the corresponding generated field for each Element private, public, protected, shared/friend, etc.

GenerateMember property: Use this property, under “Design,” to specify whether a member or field is generated for each Element. By generating members only for animated Elements, you can reduce the memory consumed by your Picture: select each non-animated Element and set GenerateMember to false.

Known Issues

C++ Picture Designer: The VG.net Picture Designer works for C++ classes. Unfortunately a C++ compiler bug prevents use of the generated files in Visual Studio.

Superflous Toolbox Items: If you find your projects are opening or closing slowly, try resetting the toolbox. Another solution is to delete .suo files periodically. Set the option Windows Forms Designer\AutoToolboxPopulate to false, to avoid creating bad toolbox items.

7. Changes

Versions 7.4a, 6.4a, and 5.4a

Designer Enhancements and Bug Fixes

• Most of the Picture Designer dialog windows are redesigned to reduce their size and make them more usable with all environment font sizes.
• In the sample area of the PathGradientFill editing control, sometimes the focus adornment would fail to appear. This problem is fixed.

Bug Fixes and Breaking Changes

• Given a Shape with no points, the PathInterpolator class could throw a NullReferenceException in the PositionAtLength and FindClosestPosition methods. This problem is fixed.
• Due to a design flaw, we felt it was necessary to introduce breaking changes to user-defined classes derived from CustomElement. To correct the flaw, we removed the following methods: IFillParent.GetDisplayedFill, IStrokeParent.GetDisplayedStroke, ITextAppearanceParent.GetDisplayedTextAppearance, and IRenderAppearanceParent.GetDisplayedRenderAppearance. As part of this design change, we reduced the amount of code required when deriving from the CustomElement class. To correct a derived class, remove inheritance of these interfaces from your class: IFillParent, IStrokeParent, and ITextAppearanceParent (these interfaces are now implemented in CustomElement). Also remove related properties and methods, such as the Fill property, the ResetFill method, the Stroke property, etc. The following properties are removed from the CustomElement class: InternalFill, InternalStroke, and InternalTextAppearance. Use instead these newly added properties: Fill, Stroke, and TextAppearance. You can also use the new CustomElement methods GetDisplayedFill, GetDisplayedStroke, and GetDisplayedTextAppearance, to obtain combined appearance objects for rendering.

Samples

• The following CustomElement based sample projects changed to accomodate the API changes described above: PathTextSample, CustomElements, Effects, Industrial, and ParticleSystemSample. If you need guidance on how you should implement your own class deriving from CustomElement, please examine those sample projects.

Versions 6.3b and 5.3b

Bug Fixes

• A memory leak in ChildCollection.DisposeAll is eliminated. This memory leak is the same as reported in versions 6.3a and 5.3a below. It was not completely eliminated in those versions.
• The Display.Update method, called during each animation tick, could throw a NullReferenceException occasionally when Elements are Disposed in mouse event handlers. In the call stack, you would see the method Picture.o at the bottom, if you caught this exception. Because the exception was caught internally, it never caused a crash, but it was annoying. This problem is fixed.

Samples

• In the Industrial, StripCharts, and StripChartsVB samples, you can now use integer, DateTime, or string labels on the horizontal axis of a StripChart. DateTime and string labels store a DateTime or string per data point. Because a rotating array is used, there is no additionl memory consumption once the capacity of the StripChart is reached.
• The StripChart sample is more memory efficient, reusing a pool of PointText objects on the horizontal axis.
• Corrected the post build events for the CustomElements and Industrial samples. They were not copying the output dlls to the correct directory, so the StripChartsVB project was not able to use the output dlls.

Versions 6.3a and 5.3a

Bug Fixes

• When the Enabled property on a Sub Picture was set to false, nested Sub Pictures within this may have computed their PixelBounds incorrectly. This problem was likely to occur after a Canvas was resized. The incorrect PixelBounds could cause Elements to fail to draw, or make it impossible to hit them with the mouse. This problem is fixed.
• The Prodige.Drawing.Image class has a method called MatchImageSize, taking a Picture parameter. A bug introduced in 2007 caused the Picture parameter to be ignored. It is not longer ignored; the Picture parameter is used if the Image is not attached to any Picture, or it cannot find a matching ImageData. In this case, MatchImageSize will look up the ImageData using the specified Picture.
• The ChildCollection.Remove method could throw an exception. ChildCollection is the type returned by the Picture.Elements and Group.Elements properties. The exception could be thrown, in rare circumstances, when calling the Remove method in a Picture.Dispose method override. This problem is fixed.
• A memory leak in ChildCollection.DisposeAll is eliminated. If a Picture or Group, was not Visible, or its displaying Form was minimized, and a program periodically created and added new Elements to a Picture or Group, as during an animation, and those Elements were disposed via ChildCollectionDisposeAll, memory could be leaked up until the time the Picture or Group became visible again. Over time, this could add up to a substantial use of memory. This problem is fixed. A work around in previous versions of VG.net is to call Clear instead of DisposeAll. The problem is discussed here: Memory Leak. UPDATE: This memory leak was not completely eliminated until versions 6.3b and 5.3b.

Versions 6.2 and 5.2

Designer Enhancements

• The new Center Selection button, in the Drawing Toobar, pans the designer surface to center the selected Elements.
• Double-clicking on a Group makes it the Active Group. When a Group is active, double clicking on the background deactivates the Active Group.
• You can now make a nested Group the Active Group. The Group can be nested to any depth. Formerly, you could only make a top-level Group the Active Group.
• With keyboard focus in the designer surface, use the following keyboard shortcuts:
  • Ctrl+Plus: zooms in
  • Ctrl+Minus: zooms out
  • Ctrl+Zero: zooms to 100%
  • Ctrl+Home: pans to center the selected Elements
• Use the new PixelSnapMode property, in the RenderAppearance class, to increase the clarity of thin lines, or the edges of rectangles, by causing points to be snapped (or rounded) to integer pixel coordinates. PixelSnapMode has several values:
  • None: the default value, which may cause thin lines to appear blurry.
  • Absolute: points are snapped to pixels by rounding absolute coordinates. This mode is suitable for large or static Elements. Tickmarks on a gauge or grid lines work well using Absolute.
  • VectorCenter: the Element's Center is snapped to a pixel point. The points on a Shape are then snapped as follows: the vector from the Center to each point is computed, and snapped to a pixel boundary. By snapping vectors rather than points, a small Shape retains its relative point positions on the screen, preserving its symmetry, and a consistent size relative to other small shapes. VectorCenter also avoids a "wiggling" effect that would occur when moving small Shapes, if Absolute were used instead.
  • BoundsAbsolute: The upper left and lower right corner of the Element's Bounds are snapped by rounding their absolute coordinates. The interior points in a Polyline or Path are not snapped.

Samples

• A Visual Basic version of the DragDropSample is now installed in the Samples folder. It is called DragDropSampleVB.
• A Visual Basic version of the StripCharts project is now installed by the Extras package. Note that the libraries used by this project are written in C#; only the top-level application could be converted to Visual Basic.
• The ThemedRobot and ThemedRobotVB samples, in the Extras package, demonstrate how to use Groups, Rotation transformations, and TransformationReference settings to create a segmented robot arm. The samples also show a solution to the problem: how do we set the angles in a robot arm, to move the gripper to a point in space?

Bug Fixes and Obsolete Members

• FMatrix.TransformSize produced an incorrect result if the FMatrix contained rotation components. This problem is fixed.
• If a top-level Picture was detached from a Canvas or TranslucentForm, from within a mouse event handler, a NullReferenceException might occur at a later time. This problem is fixed.
• Versions 5.2b, 6.2b: when running the debugger, and the VG.net designer was in Active Group Mode, double clicking on an empty area in the designer crashed Visual Studio. This problem is fixed.
• Versions 5.2b, 6.2b: for both rotation and shearing operations in the designer, dragging the rotation or shearing adornment did not track the mouse correctly if the selected Element(s) had a negative Scaling in either dimension. These problems are fixed.
• Versions 5.2b, 6.2b: various dialog layout problems in the designer were corrected.
• Versions 5.2b, 6.2b: corrected the Transformation(FMatrix m, Vector reference) constructor: when the FMatrix scaling was negative in the Y dimension, the sign of the Shearing of the Transformation instance was incorrectly reversed. If you previously compensated for this bug by reversing the sign of the Shearing property, remove the compensation.
• Versions 5.2b, 6.2b: Vector.GetShear is simplified; it no longer uses Math.Abs.

Versions 3.1, 4.1, 5.1

Designer Enhancements

• Use the new Theme class to collect common Style and ImageData objects in a single place. You can then reuse the common objects across multiple top-level Pictures. For more information, see the section titled "Themes" in the VG.net Users Guide, and the new ThemeSample project.
• The Picture, TranslucentForm, and Theme class templates all use partial classes now.
• Use the new "Save Bitmap" verb to save a bitmap rendering of any selected Element, or the entire Picture. You will find this verb at the bottom of the Properties window. If you select the root Picture, the portion currently visible is rendered. Resize the pop-up dialog to change the size of the bitmap before saving.

Run-time Only Enhancements

• The Prodige.Serialization namespace is added to Prodige.Drawing.dll. This namespace contains classes for saving and restoring object graphs to compact files or streams. Use Serializer to save objects, and Deserializer to restore objects. Unlike the serialization support built into the .NET framework, the classes in Prodige.Serialization are designed to: minimize file size; maximize speed, operating without reflection or boxing of value types; and provide infinite upward compatiblity for serialized files. Read more about serialization features in the section titled “Serialization,” in the Users Guide. See the new SerializationSample project for a demonstration of serialization.
• All VG.net graphical objects are serializable.
• The Extras package contains several new samples, including: gel and shine rectangle components, a strip chart, scada components, and bitmap effects.
• Please see the new BirdsEyeView sample project to see how to create a map overlay showing a birds eye view.
• Hardware accelerated scrolling for the Canvas: by default, all scrolling using the Canvas is hardware accelerated. We call this fast scrolling. You can take advantage of this by setting Canvas.AutoScrollPicture to true, by scrolling the Canvas using the Pan property, or by changing the top-level Picture.Translation property. Modify Picture.ScrollingMode to change the scrolling behavior. The ScrollingScalability sample allows you to experiment with ScrollingMode.
• The new CustomElement method, TranslateDeviceCoordinates, must be overridden if your CustomElement caches device coordinates. The method is called when fast scrolling occurs. You must apply the translation specified by DrawContext.DeviceTranslationX and DeviceTranslationY.
• The new DrawContext properties DeviceTranslationX and DeviceTranslationY are set if a fast scrolling operation has occurred. Use the properties to determine how much to translate device coordinate fields within a CustomElement.TranslateDeviceCoordinates override. You can also use the new properties to determine how much to scroll internal bitmap buffers.
• The new DrawContext.IntersectsClipRegion method determines if only a portion of a CustomElement needs to be drawn. Use this method in a CustomElement.DrawCore override.
• To detect multi-threading problems, Element methods and properties now throw an exception if you modify an Element from a non-UI thread. There is one circumstance where you can safely modify an Element outside a UI thread. Before you attach an Element to a display hierarchy, ultimately rooted in a Canvas, you may safely create or modify the Element and its children from any thread, as long as you take care to prevent simultaneous modification from multiple threads. This means you can create an Element hierarchy on a background thread, and pass it to the UI thread using Control.BeginInvoke. This technique is demonstrated in the SplashScreenSample project.
• PathInterpolater now works on closed Shapes, connecting the last point in the Shape to the first point.
• Use the new Style.Equivalent method to determine if two Styles have equivalent property settings and child objects.
• Use the new Display.Animated property to determine if the animation timer is enabled.
• The new FMatrix method EqualsIgnoringTranslation compares two FMatrix structures, ignoring translation components.
• Use the new TranslucentForm.SaveDesktopBounds and RestoreDesktopBounds methods to save and restore the value of the DesktopBounds property in an internal instance field.
• Use the new TranslucentForm.FillScreen method to resize a TranslucentForm to fill as much of the screen as possible, while preserving the Picture aspect ratio. Use RestoreDesktopBounds to restore the TranslucentForm to its previous DesktopBounds value. It is better to use FillScreen instead of WindowState.Maximized, to avoid flicker. The new IsMaximized property indicates if FillScreen was invoked. The TranslucentFormTips sample uses FillScreen.
• The RenderTo method is moved from Picture to Element, so you can render any Element to a Graphics or Bitmap. Use the new RenderTo overload taking an FMatrix to apply a top-level transformation without modifying any objects. This overload is demonstrated in the BirdsEyeViewSample, in the Extras package.
• The RenderTo method no longer causes a Picture to be repainted, when attached to a Canvas. This makes the RenderTo method more efficient for applications such as map overlays.
• The Element.RenderTo method now accounts for all appearance property settings on all ancestors, including Styles, ThemeReferences, and local appearance properties. You can render in isolation any Element at any level in the display hierarchy.
• Use the following new methods on DrawContext to determine combined, displayed Appearance properties when rendering a CustomElement. The new methods are: GetDisplayedFill, GetDisplayedStroke, GetDisplayedTextAppearance, and GetDisplayedRenderAppearance. Each takes an optional Style name and an optional local Appearance object (Fill, etc).

Bug Fixes and Obsolete Members

• A TranslucentForm did not behave consistently when modifying Size or DesktopBounds. Sometimes the TranslucentForm would not have the correct size on initial display, and it would behave differently if modified within a set of BeginInit and EndInit calls. These problems and others are fixed. Much of the TranslucentForm class is rewritten.
• The WindowOperation.Maximize enum value is now implemented correctly when used as a value of an Element in a TranslucentForm. This value causes the TranslucentForm to be maximized when the user presses the mouse over the corresponding Element, if the TranslucentForm is not already maximized. If the TranslucentForm is maximized, it returns to its previous size. The WindowOperation.Restore enum value is now obsolete, as Maximize serves the same purpose. Note that a TranslucentForm does not use WindowState.Maximized, even when maximized.
• Use the new TranslucentForm.SetDesktopBoundsCentered method to center the bounds of a TranslucentForm within a specified desktop bounds, while preserving the aspect ratio of the Picture.
• The TranslucentForm.Padding property is renamed to PicturePadding, and Padding is obsolete.
• Stroked text did not respect the TextAppearance.Padding property. This problem is fixed.
• If you copied and pasted an Element from one Picture to another, in a Visual Basic project, the Name property was not preserved in the copy, even if no naming conflict existed. This problem is fixed.
• If you copied an Element using control-drag, the Enabled and Visible properties were not always copied correctly. For sub Pictures, default appearance properties (Fill, etc) were not always copied correctly. Both problems are fixed.
• If you duplicated a Group using control-drag, then performed an Undo followed by a Redo operation, the new Group's Elements property was no longer serialized. This problem is fixed.
• The top-level Picture “properties”, called Language and Localization, were duplicated in Visual Studio 2005 and could behave incorrectly. This problem is fixed.
• When a top-level Picture was disposed in a mouse event handler, it could cause a crash. This bug is fixed.
• The Element.DrawAction property was not correctly cloned by an Element.Clone operation. This bug is fixed.
• If you repeatedly modified invisible Elements connected to a visible display hierarchy, over time VG.net might consume greater amounts of memory and become slow. This bug is fixed.
• The performance of StyleCollection.Add is improved.
• The PictureImporter infrastructure now supports more than one importer in the designer. It was inadvertently restricted to a single importer dll.
• Newly created Prodige.Drawing.Image objects incorrectly recorded their ImageData and Size properties, causing redo to behave incorrectly in the designer. This problem is fixed.
• Fixed a bug occurring when Canvas.AutoSizePicture is true. The bug occurred when the Canvas had the same aspect ratio as the top-level Picture, and the Canvas was resized. Sometimes the Picture resized incorrectly.
• The Canvas.Pan property no longer throws an exception if accessed when the Canvas.Picture property is set to null.
• The Drawing toolbar in Visual Studio should now work better in non-English locales.
• The MultiPointShape.Path property is obsolete. Use GetGraphicsPath instead.
• ImageLoadType.Embedded replaces ImageLoadType.ResX, which is now obsolete.

Versions 3.0 and 4.0

Designer Enhancements

• You may now use the Picture designer in Visual Studio 2005. VG.net versions 3.x support Visual Studio 2003, and versions 4.x support Visual Studio 2005.
• Trigger code when the mouse wheel is rotated using the new MouseWheel event in Element. Read more in Run-time Only Enhancements.
• Set the new Precedence property on a Style to OverriddenByAncestors, and the Style can be overridden by a Style with the same name in an ancestor Picture.

• Copy, paste, and cut Style objects within the Style collection editor by right-clicking over the Style list box and selecting a command. Alternatively, use the standard shortcuts:

  • Cut = Ctrl+X
  • Copy = Ctrl+C
  • Paste = Ctrl+V

  Styles may be copied and pasted from one designer to another. ImageData objects referenced in ImageFills are also copied.

Run-time Only Enhancements

• Trigger code when the mouse wheel is rotated using the new MouseWheel event in Element. MouseWheel events are directed to the Element under the mouse cursor, and they are bubbled and captured as with other mouse events. A corresponding PictureMouseWheel event is in Canvas and TranslucentForm.
• Styles can now be overridden by ancestor Pictures, by changing the Precedence property. If there is any chance a Style may be overridden, call the new method RebindOverridableStyles after adding a Style to a Picture containing sub Pictures. The method call is only needed if the Pictures have been displayed: Styles are bound to referencing Elements during the first display.
• If you use different TextAppearances in your Pictures, Element text displays faster, as Fonts are now globally cached in VG.net. If you wish to dispose cached Fonts, call the new static (Shared) method DisposeCachedFonts in TextAppearance. The Font cache is automatically purged when all top-level Pictures are detached from Controls, and no Picture can be displayed.
• The following writable convenience properties are added to Element: Left, Right, Top, Bottom, CenterX, CenterY, LeftTop, RightTop, LeftBottom, and RightBottom.
• You may once again compile classes derived from BoundedShape. The internal abstract (Friend MustOverride) method in Shape that prevented compilation is now virtual, and a default implementation is provided.

Bug Fixes and Obsolete Members

• Displaying a PointText created with the PointText Clone method no longer throws an exception, and the Text property is properly copied.
• Calling Form ShowDialog from a MouseDown event handler, when the displayed Form contains a Canvas and Picture, no longer causes an exception. Calling Application.DoEvents from a mouse event handler can no longer cause an exception either.
• TransformationReference property settings, of type Absolute, are no longer lost if you open a Picture in the designer and make changes.
• Moving a Picture with a ClipRectangle, when nesting in another Picture or Group (2 or more levels down), will now properly erase the clipped sub Picture.
• The Canvas Zoom property is no longer serialized to code, as it caused strange behavior in the designer when AutoSizePicture was set to true. Properties in Picture that may also interfere with AutoSizePicture (Translation and Scaling) are also no longer serialized when the Picture is in a Form or UserControl.
• If a source code control checkout dialog popped up after moving an Element, and the checkout was canceled, the Element might remain moved. This bug is fixed.
• Certain TextAppearance settings for a PointText no longer display a wider than specified Stroke width, causing artifacts when the PointText is moved. Specifically, the problem occured when a TextAppearance had StrokeVisible set to true, did not specify a Stroke Width, and did specify some other property, such as Color.
• The IList implementation in ObjectCollection (a base class) no longer allows objects to be added to a ChildCollection or a ImageDataCollection without setting the Parent property on the child object. The interface implementation has been moved to the derived classes.

Version 2.7a

Designer Enhancements

• Use the new TranslucentForm class to replace your entire user interface with a top-level Picture, eliminating even the window border and caption. With this class, and the associated DisplayInTranslucentForm method on Picture, you can create windows with per-pixel translucency and arbitrary shapes. Edge anti-aliasing is alpha blended, making it superior to the use of the Form Region property. See the following article:

  A Resizable Vector Graphics Calculator with Per-Pixel Translucency

• Use the new WindowOperation property on Element to specify the window operation triggered by a mouse event on the Element when displayed in a TranslucentForm: Close, Minimize, resize, etc. See the article link above for more information.
• Within the Forms designer, you can now drag and drop a Picture from the Toolbox onto a Canvas to display that Picture in the Canvas. You can also select the Toolbox item and click on a Canvas. The same operations are supported for the new TranslucentForm class.
• Use the new BaseStyle property in the Style class to collect common appearance properties in a single Style that can then be inherited across mutiple Styles. BaseStyle is a string. Consider two Styles, one named Style1, and one named Common. If you set the BaseStyle property in Style1 to "Common", Style1 will inherit all the property settings in the Common Style. Changes to Common will change the appearance of all Elements that reference Style1.

Samples

• Source code for the new TranslucentCalculator and TranslucentClock samples is installed by the Extras package. The TranslucentCalculator is a "skinning" example: it demonstrates how to create a fancy user interface with gel buttons and 3D effects. It also demonstrates how to separate a user interface from core application logic. Both TranslucentCalculator and TranslucentClock use TranslucentForm.
• Use the Button base class in TranslucentCalculator to create your own custom buttons.

Run-time Only Enhancements

• All PathGradientFill display is now optimized for speed. This is good news for Pictures with 3D effects.
• In addition to the general optimization above, similar PathGradientFills used across similarly shaped Elements now share gradient cache data. Rows of buttons or other similar Elements are much faster and consume less memory. This opens up the use of 3D effects for complex interfaces. The TranslucentCalculator sample takes advantage of this feature. You do not need to make any changes to take advantage of this optimization; you merely have to use Elements with similar (combined) fill properties and shapes. Rotated Elements can also share cache data -- rotation has no effect on the ability to share.

• All mouse events in the Picture class now bubble all the way to the Canvas and TranslucentForm. The new events in Canvas and TranslucentForm:

  • PictureMouseEnter
  • PictureMouseLeave
  • PictureMouseMove
  • PictureMouseDown
  • PictureMouseUp
  • PictureClick
  • PictureDoubleClick
  • PictureMouseHover
• Use the new ElementPoint property in ElementMouseEventArgs to determine the mouse position in the coordinate space of the Element raising the event. For LeafElements, including Shapes, the point is in the Element space, the same space as the Bounds and internal points. For a Group or Picture, the point is in the Child space, the coordinate space common to all children.
• The ColorUtility.ColorCombine methods are now optimized for speed.

Bug Fixes and Obsolete Members

• A solid color Stroke, with no Color property set, but with the Opacity property set, ignored the Width property during display. This bug is fixed.
• The FSize and Vector constructors taking Double parameters are eliminated. This change was made to improve C++ support. Any code using these constructors, that no longer compiles, can be fixed with an explicit cast to float, or Single in Visual Basic, on each parameter.
• A PathGradientFill with CoordinateType set to Absolute failed to serialize correctly. This bug is fixed.

Version 2.6b

Run-time Only Enhancements

• The new GetTextPixelBounds method in the Shape and PointText classes computes the rectangular area enclosing all pixels displayed by text. This method always recomputes the correct area, returning the correct result even if the object has never been displayed. By contrast, the PixelBounds property returns a rectangle enclosing the pixels last displayed, and cannot be used before an object is first displayed.

Bug Fixes and Obsolete Members

• The CaptureMouse method failed to capture mouse input when called on a top-level Picture (a Picture connected to a Canvas). The method now works correctly.
• A non-composite Element (an Element which is not a Group or Picture) with the Enabled property set to false failed to update its PixelBounds when a Parent was transformed, zoomed, or panned, causing incorrect erasure or display. This bug has been fixed.
• When a Picture was added to a System.ComponentModel.Container, mouse events would no longer be raised. This also caused a bug in the DesignMode property, which returned true when a Picture was added to a Container. These bugs have been fixed: when a Picture is added to a Container, DesignMode returns false (except in Visual Studio), and mouse events are raised.
• The TextAppearance RenderingHint property did not function correctly. An Element with the TextAppearance.RenderingHint property set influenced the text rendering of other Elements within a Picture. This problem has been fixed.
• When serializing to a MyXaml file, a property tagged with a DesignerSerializationVisibilityAttribute with a value of DesignerSerializationVisibility.Content, which was not a collection, was incorrectly serialized in one situation: if all in the referenced object were set to default values, the property would be serialized. Now the property will not be serialized in that situation.

Version 2.6a

Designer Enhancements

• The new CornerRadii property in the Rectangle class allows you to create rounded rectangles with corners where the arc radius differs in the x and y dimensions. The new Radii structure holds values assigned to the CornerRadii property.

Run-time Only Enhancements

• The HitTest method in Element has a new overload that takes as a parameter an ElementCollection. Use this method when you would like to get the entire "stack" of Elements hit by a device point. That is, you will obtain the leaf Element hit, followed by its Parent, followed by each Parent higher in the hierarchy.
• Use the new static FindFontFamily event in the TextAppearance class to display dynamically loaded fonts. This event is raised whenever a TextAppearance needs to look up a FontFamily. If you have loaded fonts using a PrivateFontCollection, the FindFontFamily event enables you to display these private fonts. In your event handler, examine the FamilyName property of the FindFontFamilyEventArgs parameter. If the name matches one of your private family names, set the FontFamily property before returning from the event handler, and your FontFamily will be used. If there is no match, do nothing, and the normal FontFamily searching algorithm will be used. See this forum entry for some code samples: http://www.vgdotnet.com/forums/viewtopic.php?t=193
• Use the new PropertyChanged event in Element to monitor property changes. Currently this event is only raised for the Element.Parent and Picture.Control properties. In the future, this event will be raised when for many different property changes.
• Use the new TransformationReference.Origin field to set the TransformationReference of an Element to (0, 0):
  element1.TransformationReference = TransformationReference.Origin;
• Set the new static property, ManagedCodeOnly, in Display to true when you build a dll that must run in a restricted security setting, such as Internet Explorer. In the future, we will add optimizations using PInkoke that will be bypassed when ManageCodeOnly is true.

Bug Fixes and Obsolete Members

• The Zoom To Selected command, and all selection adornments now behave more logically with invisible Elements. Formerly, the command might zoom to the wrong area, or the adornments might enclose the wrong area.
• A Group containing no Elements, when cloned using the Clone method, produced a Group that threw an exception when attempting to add Elements. This bug has been fixed.
• A Group which was cloned or duplicated in the designer sometimes contained copies of the Styles and ImageData objects referenced by children of the Group. Because of this problem, the children of the Group would fail to update when the original Style or ImageData was modified. This bug has been fixed.
• FRectangle structures which are transfomed by a negative scaling factor using a Scaling or SclaingTranslation no longer result in an FRectangle with Width or Height set to a negative number.
• The Users Guide failed to open from the Start Menu shortcuts if a Visual Studio beta version was previously installed. This problem has been fixed.

Version 2.5

This version contained only internal changes.

Version 2.4b

Designer Enhancements

• If you wish to make all invisible Elements visible at design-time, select the top-level Picture and set the InvisibleAreDisplayed property to true. This has no effect at run-time.
• If you wish to be able to select disabled Elements by clicking with the mouse, select the top-level Picture and set the property DisabledArePickable to true. A "disabled" Element is one with Enabled set to false.

Run-time Only Enhancements

• The CustomElement copy constructor is now protected, to be used by derived classes. We added the InternalFill, InternalStroke, and InternalTextAppearance protected properties, as well as supporting members so that a CustomElement based class can expose a Fill, Stroke, or TextAppearance property.
• In DrawContext, we made several members public to support CustomElement derived clases: Font, TextBrush, GetFullTextBounds, GetTextPixelBounds, DrawText, PushTransformation, and PopTransformation.
• We created a preliminary CustomElement sample, which draws text along an arbitrary Shape path. If you need to build a CustomElement (an advanced topic) please request a copy of this sample. In the future the sample will be added to the Extras package.

Bug Fixes and Obsolete Members

• In the VG.net Designer Lite version only, if you attempted to exceed the object count limit, the Rotation and Shearing adornments would disappear. This bug is fixed.
• Setting the Enabled property from true to false on a Shape caused problems with mouse events and display updates, if the DrawAction was set to Fill. This bug is fixed.
• We added an overload for the Element HitTest method: bool HitTest(Vector point, out Element hitElement). The existing HitTest method has an additional boolean parameter called skipDisabled. This parameter is no longer supported, and the HitTest(Vector, bool, out Element) overload is now obsolete.

Version 2.4a

Designer Enhancements

• Text can now draw a Stroke outlining each character. The TextAppearance class has new Stroke, StrokeVisible, and FillVisible properties.
• Use the new PointText Element to place text relative to a point on the screen. PointText is specified by a single point, and never wraps. The TextAppearance HorizontalAlignment and VerticalAlignment properties control the positioning of PointText. Read the topic titled "PointText" in the Users Guide for more information.
• When using the PathGradientFill, wide and short gradients, as well as tall and narrow gradients, are now better quality, without any reduction in speed.
• When editing a PathGradientFill, if the FocusPoint adornment has been moved out of the sample entirely, a click within the sample area will move the adornment back into the sample.
• Custom colors added to the custom color list now persist between editing sessions.
• The new ScrollableArea property on Picture allows you to specify the coordinate area around which you can scroll at design-time. This allows you to easily place Elements far outside the automatically computed scrollable area. The ScrollableArea property, if set to any value other than (0, 0, 0, 0), will be used by the Canvas at run-time as well, when AutoScrollPicture is true. Read the topic titled "The Scrollable Area" in the Users Guide for more information.
• Active Group mode is added to the Picture Designer. This mode lets you work on Elements within a Group without ungrouping them. Read the topic titled "Active Group Mode" in the Users Guide for more information.
• Alignment, sizing, spacing, and centering commands have been added to the Picture Designer. These commands are on the Layout. To show the Layout toolbar, right click on an empty toolbar area in Visual Studio .NET. Read the topic titled "Layout Commands" in the Users Guide for more information.
• If you right-click on an empty area of the designer surface and select the Paste command, the pasted Element is now located at the position of the click.
• Pressing the Shift key when dragging the mouse to lasso a set of Elements now adds to the existing selection, instead of replacing it. See "Selecting Elements" in the Users Guide for more information.
• Pressing the Control key when dragging the mouse to lasso a set of Elements now performs a disjoint selection: previously selected Elements enclosed by the lasso are deselected; enclosed Elements not previously selected are selected. See "Selecting Elements" in the Users Guide for more information.
• Pressing the Alt key when pressing down the left mouse button and dragging now forces the Picture Designer to enter lasso mode, whereby you can select enclosed objects. The Alt key prevents objects underneath the mouse press from being immediately selected, so you can begin a lasso operation even if there is no empty space on the designer surface.
• The new RotationShearingAdornmentVisible property on the top-level Picture, within the Picture Designer, allows you to make the rotation and shearing adornments invisible, so they will not interfere when you have no need for rotation or shearing.
• The new HotkeyDisplay property on TextAppearance allows you to control how the "&" (ampersand) character is interpreted when displaying text. The ampersand character can now be used to underline any character in the display string.
• The "VG.net Picture" template file can now be selected from the "Add New Item…" command within a web project. This makes it easier to add Pictures to your web applications.
• The Users Guide is updated.

Run-time Only Enhancements

• The ElementHitTest and EnclosedTest methods have been moved from Picture to the base class Composite, so you can now use the methods on Groups. See "Composite class" in the Reference documentation. See "Grouping Elements" in the Users Guide for more information on Groups.
• The new CustomElement class is a base class you can use to create Elements with completely custom drawing code.
• The ElementCollection AddRange method now has an overload taking as input an EnclosedElementCollection.
• Improved PixelBounds calculation accuracy for all Shapes except Paths, which in turn has improved animation performance.
• Picture BeginInit and EndInit are now virtual, so you can override them.

Bug Fixes and Obsolete Members

• PathGradientFill objects now print correctly.
• The Picture ClipRectangle property now correctly clips when printing or using Picture.RenderTo.
• The Canvas AutoScroll property is obsolete, and will cause warnings during compilation. The new AutoScrollPicture property replaces AutoScroll.
• The Canvas AutoScrollMargin and AutoSizePadding properties are obsolete. The new PicturePadding property replaces both AutoScrollMargin and AutoSizePadding. If you currently use the AutoSizePicture property, please check to see if PicturePadding needs to be set to (0, 0) - the default is (20, 20).
• A line of pixels on the top and left of a Canvas were incorrectly drawn when the BackgroundImage property was set. This bug has been fixed.
• Many Elements no longer allow Width or Height to be set to a value less than 0, to prevent exceptions during the display pass.
• Unless SetBoundsCore is overridden, a Picture with a non-zero Width cannot have its Width set to 0. The same constraint exists for Height.
• Undo and Redo of a Closed Polyline now works correctly when editing the Polyline points.
• Invisible elements were drawn when printing or using the Picture RenderTo method. This bug has been fixed.
• Picture.Invalidate, called when a Canvas BackColor or BackgroundImage property changed, did not cause the screen to update correctly when multiple Canvases were used simultaneously. This bug has been fixed.

Version 2.3

• Animation performance has been significantly improved in complex Pictures with many objects, when several widely separated areas of the screen are animated simultaneously. Read more, and run the sample SCADA simulation at:

  http://weblogs.asp.net/frank_hileman/archive/2004/12/06/276001.aspx

• Several new commands have been added to the Picture Designer:
  • TAB selects the next Element in the z-order, within the containing Parent, which may be a Group. SHIFT + TAB selects the previous Element.
  • ARROW keys move the selected Elements in the direction of the arrow, in increments of the grid spacing. SHIFT + ARROW key combinations increase or decrease the size of Selected Elements. The CTRL key, in conjunction with any of the movement or resize key combinations, will change the unit of increment to a single pixel.
  • Bring Forward and Send Backward move Elements forward and backward in the z-order. These were added in 2.2b.
  See the new help topic titled "Picture Designer Default Shortcut Keys" for more information.
• The new PictureImporter class can be used to provide plug-ins to the Picture Designer that can convert vector graphics data in another format to a VG.net Picture, either by using a file or the clipboard. PictureImporters can also be used at runtime. If you wish to create or sell a custom PictureImporter, please download the template solution at:

  http://www.vgdotnet.com/support_files/TestImporter.zip

• When Canvas.AutoScroll was turned on, then off, a NullReferenceException could be thrown. This bug has been fixed.
• Potential change in behavior: In a PathGradientFill, the FocusScaling propery now overrides any setting on a PathGradientFill in a parent. In other words, this property is no longer subject to "appearance inheritance". This was done to ensure that child fills with a default setting for FocusScaling produce the correct effect.
• The ElementCollection.AddRange method can now be used to transfer child Elements from one Composite (Group or Picture) to another, without throwing a NullReferenceException.
• The new IsBoundsValid property on the Composite class determines if a Composite (Group or Picture) has a valid Bounds. An invalid Bounds is produced when a Group or Picture contains no child Elements. Composites with an invalid Bounds no longer contribute the point (0, 0) to parent Composite Bounds computations -- they are ignored in these computations.
• The Vector.LineSegmentIntersection method is added. This method determines if line segments intersect, and if an intersection is found, returns the point of intersection.
• The FRectangle.RelativeToAbsoluteRectangle method is added. Use this to convert relative rectangles, expressed as fractions of the width and height, to absolute rectangles.

Version 2.2

• The PathGradientFill class has been added. This enables you to create radial gradient fills, or gradient fills based on any path or Element shape. It is very useful for 3D effects. Please see the VG.net blog for tips on using the PathGradientFill for 3D effects: http://weblogs.asp.net/frank_hileman. By default, PathGradientFills are cached as images for speed. You can modify the behavior of this caching with the PathGradientFill.Quality property.
• The PathInterpolater class, the Shape.PathInterpolator property, the Element.PathMove method, and the PathPosition structure have been added. The PathInterpolator object can be used to convert arc lengths to points and tangents on a Shape, or vice-versa. It can also be used to find the closest point on the Shape path to an arbitrary point. PathMove moves any Element along the path defined by any Shape. PathMove will optionally rotate the Element to align with the tangent to the path. The new PathMove sample demonstrates how to use these new types and members.
• The AnalogClock sample has been updated to use path gradients. The EventHandling sample has also been given a much-needed face-lift :).
• The following properties in LinearGradientFill have been obsoleted and replaced by new ones: BlendFocus replaces Focus; BlendFocusScale replaced FocusScale; CoordinateType replaces BoundsType. The FillCoordinateType enum replaces FillBoundsType. Your existing Pictures will compile, but you can eliminate obsolete warnings by running the ReplaceNames macro in ProdigeNameFix.vb, in the VG.net installation folder.
• Copying objects in the designer sometimes inverted the order in which local appearance properties and Style references were applied -- the Style incorrectly taking precedence. This bug has been fixed.
• The MoveForward and SendBackward commands have been added to the Picture Designer. These allow you to move one or more Elements forward or backward a single index in the z-order.
• When editing path points in the Picture Designer, control point adornments now appear in front of anchor point adorments, making it possible to grab previously obscured control points.
• The Fill dialog box in the Picture Designer now displays previews of the selected Element in the sample boxes.
• In the Picture Designer, all changes to Style objects now immediately affect the display surface. If you cancel a change, the changes disappear.
• In the Picture Designer, the point editing mode is cancelled when a modal dialog is opened.
• The ImageDataObjects collection in a Picture is now cloned when the Picture is cloned.
• The Picture.DisplayInForm method now uses the monitor associated with the Form to compute the optimum size.
• Potential breaking change: Shape.GetGraphicsPath is now called GetTransformedGraphicsPath, and GetGraphicsPath now returns an untransformed GraphicsPath. The method Shape.AddToGraphicsPath has been added.
• The gradient displayed by LinearGradientFill objects can now be defined using two points instead of a rectangle. This is useful when rotating a gradient within a circular or elliptical object, such as an Ellipse, Arc, or Pie. The StartPoint and EndPoint properties define a vector for the gradient line.
• The Click and DoubleClick events are now correctly raised only for Elements which also received a MouseDown event. Formerly, it would be raised for any Element over which a mouse button was released.
• It is now possible to repair a VG.net installation without keycode errors.
• The new Element.GetTopPicture method returns the top-level Picture displaying an Element. The new Element.GetCanvas method returns the Canvas displaying an Element.
• Added the RelativeToAbsoluteRectangle method to the FRectangle class, and the RelativeToAbsolutePoint method to the Vector class.
• Added the DistanceToSegment method to the Vector class, for computing the distance from a point to a line segment.
• The reference bounding box used to display linear and path gradient fills for text is now "tighter" -- fitting the text bounds more closely. Formerly the Element bounds was used. Now you can create more dramatic gradients without editing the Bounds property of the LinearGradientFill.
• A new ScalingTranslation constructor has been added for creating a ScalingTranslation that transforms a source rectangle to a destination rectangle using a scaling equal in both dimensions. This constructor has a Boolean third parameter.
• MultiPointShape objects with a zero-sized Width and Height no longer throw an exception during the display pass.

Version 2.1b

• Multi-line text can now be entered into any Shape in the Picture designer. Use the "..." button to open a dialog box in which you can enter multi-line text.
• The rotation and shear adornments are hidden in the Picture designer when an Element is less than 20 pixels long and wide. To show the adornments for small Elements, zoom in, or select the Element and use "Zoom to Selected" in the Drawing toolbar.
• The ImageZoom sample has been added to the Extras package for VG.net customers. This sample demonstrates how to use the ClipRectangle property and ZoomToParentRectangle method to zoom to selected areas of an Image. The sample is not included in the Lite version.
• The Scalability sample incorrectly computed average modification times; they were consistently low. This bug has been fixed.
• TextAppearance and Stroke objects with a SolidFill with only Opacity set (not Color) did not correctly serialize the Opacity, and instead serialized the Color, making it impossible to set only opacity. This bug has been fixed.
• The ClipRectangle property can now be set on a Sub Picture within the designer.
• The ClipRectangle on a Picture now affects its PixelBounds (it is intersected) as well as the internal bounds reported to any Parent of the Picture, when that Parent computes its own Bounds.
• The ZoomToParentRectangle method was added to Picture. This method is used in conjunction with ClipRectangle to zoom a SubPicture to a rectangle specified in the Parent coordinate space.
• Resizing or moving a Sub Picture within the designer will now resize and move the ClipRectangle on that Sub Picture.
• The ClipRectangle on a Sub Picture now correctly prevents mouse events from being raised on the clipped portion of child Elements.
• In some circumstances, setting the ClipRectangle on a Sub Picture could cause incorrect rendering of Elements higher in the z-order. This bug has been fixed.
• Sub Pictures with a ClipRectangle set cannot be grouped within the Picture designer. This restriction was made to prevent problems when later transforming the Group. The ClipRectangle property is specifically for creating "view ports" on the objects within a Sub Picture.
• Dragging and dropping a set of Elements from one designer to another could not always be "undone" correctly. The designer transaction was incorrectly recorded. This bug has been fixed.
• The Stroke TransformWidth property, when set to false, now produces the correct pen width when the Picture PageUnit or PageScale properties are set to non-default values.
• Polylines with a zero sized width or height no longer throw an exception if rendered with a LinearGradientFill Stroke.

Version 2.1

• The WebControls sample has been added. This sample demonstrates how to use VG.net graphics within an Internet Explorer client. Any VG.net-based Control can be used in Internet Explorer. The sample also demonstrates how to use a single Style object to modify the base color of an entire user interface. The source code for this sample is in the Extras package available to VG.net customers. The source code is not included in the Lite version.
• The Sockets sample has been added. This sample is divided into two parts: a client and a server. The server generates simulated real-time data and sends that data to the client via TCP/IP. The client provides a visualization using some vector graphics components.
• The ToolTip sample has been added, demonstrating how to use the new MouseHover event available on every Element. This sample also demonstrates how to use IExtenderProvider to provide pseudo-properties on Elements.
• The Scalability sample has been added. This sample provides a framework for performance testing. It is used by the VG.net developers to test and optimize the display engine. The sample can test from 1,000 to 500,000 VG.net Elements.
• The Picture designer now has basic printing support for Pictures. This feature is not available in the Lite version.
• The RenderTo(Graphics) function has been added to Picture. This function serves several purposes. You might use it to add printing support to your applications, or you might use it to render Pictures to bitmaps on a web server, and transmit the bitmaps to the web client. This function is not available in the Lite version.
• The MouseHover event has been added. This event is raised on every enabled Element whenever the mouse pointer hovers over the Element for the time specified in Picture.MouseHoverTime.
• The CaptureMouse and ReleaseMouseCapture functions have been added to Element. CaptureMouse captures all mouse move events, directing them toward a single Element, until ReleaseMouseCapture is called. With these functions, you can create sliders and knobs that behave in the same way as a Windows.Forms slider.
• The Stroke.TransformWidth property now works correctly, and can be set within the Stroke properties dialog in the Picture Designer. TransformWidth defaults to true. When a Stroke's TransformWidth is set to false, Shape lines and edges do not change width as you zoom in and out. The width is constant, regardless of the transformations on Shape or its parents.
• The performance of the run-time engine has been improved.
• A call to Picture.Elements.DisposeAll now correctly causes the erasure of all disposed Elements.
• Invisible Elements that were made visible once incorrectly raised mouse events (acting as if enabled). Invisible Elements now correctly behave as if Enabled equals false, under all circumstances.
• Several changes were made to simplify the use of VG.net Pictures within Internet Explorer. It is no longer necessary to give Prodige.Drawing.dll any special permissions. Addionally, thread safety was added to critical data structures (IE uses multi-threading even for paint events).
• The AutoSizePicture property in Canvas sometimes caused Pictures to be incorrectly positioned. This bug has been fixed.
• BoundedElement objects (Rectangle, Circle, etc) no longer throw exceptions during the display pass if Width or Height is set to 0.
• Pictures contained in external assemblies could not be added to the Visual Studio .NET ToolBox. This bug has been fixed.
• Images saved within MyXaml files from the Picture Designer now correctly save in their original format, instead of converting to PNG.
• Tag properties containing strings now serialize correctly to MyXaml.
• Prodige assemblies are now installed in the GAC. The prevents an error from occuring when a Picture is opened after previously opening a closing a solution in Visual Studio .NET.

8. Future Features

To request an enhancment, please post to the Enhancements forum at:

www.vgdotnet.com/forums

Some possible future features:

• Layout engines, including integrated support for anchoring and docking.
• Integrated support for shadows.
• Digital filter effects, such as blurring, and the ability to add custom filters.
• Buffering of an Element or the background behind an Element, to speed up complex, non-animated objects.
• Aggressive pruning of Elements whose geometry lies outside the clipping region, preventing the computation of the Element PixelBounds when pruned. Currently we compute the PixelBounds, since many Elements (thick lines, text) may extend past their geometric bounds into the clipping region. Aggressive pruning speeds up scrolling and zooming on thousands of objects, when a smaller percentage overlap the clipping region.
• A Layer property on each Element, containing a string, will allow you to assign any Element, at any level, to a Canvas-wide Layer. You can toggle the visibility or Enabled property on all Elements associated with a particular layer by modifying a property on the Layer. This is useful for showing/hiding levels of detail in large scale SCADA and map displays.
• Clipping on Groups.
• Path clipping on Pictures. Rectangular clipping is currently supported.
• An Opacity property for an entire Element or Picture; currently opacity is defined separately for each BrushStyle or PenStyle.

Copyright © 2003-2008 Prodige Software Corporation. All rights reserved.