API Changes in Surface 2.0
This topic contains a list of the new, changed, and removed APIs in Microsoft Surface 2.0.
Surface Migration PowerToy
If you use the Surface Migration PowerToy to upgrade a Core layer or Presentation layer Surface 1.0 SP1 project to Surface 2.0, most of your code will be updated for you. If your project uses any functionality that had more than its syntax changed, you will have to manually update your code. For example, the following features must be updated manually:
- Manipulations and inertia Manipulation functionality has been added to .NET 4 to the System.Windows.Input.Manipulations namespace. For more information, see Using Manipulations and Inertia in an XNA Application and Input Overview (WPF).
- Tap and hold gestures Tap and hold events have been moved to routed events in the TouchExtensions class. For an example, see the AddHoldGestureHandler method.
- Tag APIs and object registration Byte tags and identity tags have been replaced by a more generic tag type, defined in the Core layer TagData structure and the Presentation layer TagData structure. You must manually update your code, the tag definitions in your application registration XML file, and register tag objects using the new XML file format instead of registering tags in the registry. For more information, see Tagged Object Recognition, Registering Standard Applications, and Specifying Physical Attributes of Tagged Objects.
- Application registration The application registration XML file has been updated to use the more generic tag APIs and to remove the need for a preview image. For more information, see Registering Standard Applications.
- Version numbers in assemblies The version number in the assemblies has been updated to v2.0. For example, in a Presentation layer application, the reference to the resource dictionary must be updated to <ResourceDictionary Source="/Microsoft.Surface.Presentation.Generic;v2.0.0.0; .../>
For specific guidance about manually updating these features in your code, see the documentation that comes with the Migration PowerToy.
API Changes
The following table lists all API changes between previous versions of Surface and Surface 2.0.
| API name | Surface 1.0 SP1 | Surface Toolkit for Windows | Surface 2.0 | Notes |
|---|---|---|---|---|
| Microsoft.Surface.ApplicationLauncher | yes | Moved to the ApplicationServices class. Some members were renamed and repurposed.
New members were added to provide more information about user sessions. | ||
| yes | Replaced the ApplicationLauncher class. Some members were renamed and repurposed. New members were added to provide more information about user sessions. | |||
| Microsoft.Surface.Core.ByteTag | yes | Removed. Byte tags and identity tags have been replaced by a more generic tag type, defined in the TagData structure. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| Microsoft.Surface.Core.Contact | yes | Moved to the TouchPoint class, to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | ||
| Microsoft.Surface.Core.ContactBounds | yes | Moved to the TouchBounds class, to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | ||
| Microsoft.Surface.Core.ContactEventArgs | yes | Moved to the TouchEventArgs class, to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | ||
| Microsoft.Surface.Core.ContactTarget | yes | Moved to the TouchTarget class, to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | ||
| yes | yes | Updated. The overloaded TryGetRawImage methods that took a Contact as a parameter have been updated to take a TouchPoint instead. | ||
| Microsoft.Surface.Core.IdentityTag | yes | Removed. Byte tags and identity tags have been replaced by a more generic tag type, defined in the TagData structure. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| Microsoft.Surface.Core.ImageType.Binarized | yes | Removed. Binarized images are no longer supported. Use Normalized instead. | ||
| yes | yes | Most members moved to a new InteractiveSurfaceDevice class. This class now contains only one property to obtain a pointer to the primary interactive surface device. | ||
| yes | Added to include the members from the old InteractiveSurface class. Many members have been added to detect hardware capabilities and obtain data about device bounds. | |||
| Microsoft.Surface.Core.KeyboardLayout | yes | Moved to the Microsoft.Surface namespace. | ||
| Microsoft.Surface.Core.Manipulations | yes | Removed. Manipulation functionality has been added to .NET 4. You must manually convert your code to use the System.Windows.Input.Manipulations namespace. | ||
| Microsoft.Surface.Core.ReadOnlyContactCollection | yes | Moved to the ReadOnlyTouchPointCollection class, to maintain naming parity with the new .NET 4 touch functionality that is now used by Core layer applications. | ||
| yes | Replaces the ReadOnlyContactCollection class. | |||
| Microsoft.Surface.Core.SurfaceKeyboard | yes | Moved to the Microsoft.Surface namespace. | ||
| yes | yes | Updated to support the new generic tag format. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| Microsoft.Surface.Core.TagType | yes | Removed because of the new generic tag format. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| yes | Added to be used by the InteractiveSurfaceDevice class to work with hardware that is capable of reporting tilt values, such as devices made for Surface. | |||
| yes | Replaces the ContactBounds class to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | |||
| yes | Replaces the ContactEventArgs to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | |||
| yes | Replaces Contact to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | |||
| yes | Replaces ContactTarget to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. New members have been added to support tag and hold gestures. | |||
| yes | Replaces the Microsoft.Surface.Core.KeyboardLayout enumeration and now provides access to the Surface keyboard from both Core and Presentation layer applications. | |||
| Microsoft.Surface.OrientationChangedEventArgs | yes | Removed. The orientation of Launcher is reported once, when an application loads. | ||
| Microsoft.Surface.Presentation.ByteTag | yes | Removed. Byte tags and identity tags have been replaced by a more generic tag type, defined in the TagData structure. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| Microsoft.Surface.Presentation.Contact | yes | Removed. Touch functionality is now included in .NET 4, in the TouchPoint class. Surface controls now inherit most of their touch functionality from UIElement. Extra touch functionality is provided by the SurfaceTouchExtensions class. | ||
| Microsoft.Surface.Presentation.ContactEventArgs | yes | Removed. Touch functionality is now included in .NET 4, in the TouchEventArgs class. | ||
| Microsoft.Surface.Presentation.Contacts | yes | Removed. Touch functionality is now included in .NET 4, in the TouchPointCollection class. | ||
| Microsoft.Surface.Presentation.Controls.ByteTagVisualizationDefinition | yes | Removed. Byte tags and identity tags have been replaced by a more generic tag type. To define a visualization, use the new TagVisualizationDefinition class. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| Microsoft.Surface.Presentation.Controls.ContactVisualizations | yes | Removed. The classes have been moved to the Microsoft.Surface.Presentation.Controls.TouchVisualizations namespace and renamed, to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | ||
| yes | yes | Added to provide manipulation data from the manipulation functionality that has been added to .NET 4. You must manually convert your manipulation code to use the System.Windows.Input.Manipulations namespace. | ||
| yes | yes | Added to provide manipulation data from the manipulation functionality that has been added to .NET 4. You must manually convert your manipulation code to use the System.Windows.Input.Manipulations namespace. | ||
| yes | yes | Added to provide manipulation data from the manipulation functionality that has been added to .NET 4. You must manually convert your manipulation code to use the System.Windows.Input.Manipulations namespace. | ||
| yes | yes | Updated to include a new property, IsSelected. Also, all contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | ||
| yes | yes | Updated to include a new property, IsSelected. Also, all contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | ||
| Microsoft.Surface.Presentation.Controls. IdentityTagVisualizationDefinition | yes | Removed. Byte tags and identity tags have been replaced by a more generic tag type. To define a visualization, use the new TagVisualizationDefinition class. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| Microsoft.Surface.Presentation.Controls.Primitives.SurfacePopup | yes | Removed because the touch functionality required by Surface is now included in .NET 4. | ||
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| Microsoft.Surface.Presentation.Controls.Primitives.SurfaceSelector | yes | Removed because the touch functionality required by Surface is now included in .NET 4. | ||
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| Microsoft.Surface.Presentation.Controls.Primitives.SurfaceTrack | yes | Removed because the touch functionality required by Surface is now included in .NET 4. | ||
| yes | yes | Added. This class provides custom behavior for the ScatterView control. | ||
| Microsoft.Surface.Presentation.Controls. ScatterManipulationCompletedEventArgs | yes | Removed because manipulation behavior is now inherited from .NET 4. Use the ManipulationCompletedEventArgs class instead. | ||
| Microsoft.Surface.Presentation.Controls. ScatterManipulationDeltaEventArgs | yes | Removed because manipulation behavior is now inherited from .NET 4. Use the ManipulationDeltaEventArgs class instead. | ||
| Microsoft.Surface.Presentation.Controls. ScatterManipulationStartedEventArgs | yes | Removed because manipulation behavior is now inherited from .NET 4. Use the ManipulationStartedEventArgs class instead. | ||
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| Microsoft.Surface.Presentation.Controls.SurfaceContentControl | yes | Removed because touch functionality is now inherited from .NET 4. Surface content controls inherit from ContentControl. | ||
| Microsoft.Surface.Presentation.Controls.SurfaceContextMenu | yes | Removed because touch functionality is now inherited from .NET 4. | ||
| Microsoft.Surface.Presentation.Controls.SurfaceControl | yes | Removed because touch functionality is now inherited from .NET 4. Surface controls inherit from Control. | ||
| Microsoft.Surface.Presentation.Controls.SurfaceFrameworkElement | yes | Removed because touch functionality is now inherited from .NET 4. Surface controls inherit from FrameworkElement. | ||
| Microsoft.Surface.Presentation.Controls.SurfaceHeaderedItemsControl | yes | Removed because touch functionality is now inherited from .NET 4. Surface headered items controls inherit from HeaderedItemsControl. | ||
| yes | yes | yes | Updated. Most contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. UsesContactShape has been renamed to UsesTouchShape. | |
| Microsoft.Surface.Presentation.Controls.SurfaceItemsControl | yes | Removed because touch functionality is now inherited from .NET 4. Surface items controls inherit from ItemsControl. | ||
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| Microsoft.Surface.Presentation.Controls.SurfaceMenu | yes | Removed because touch functionality is now inherited from .NET 4. | ||
| Microsoft.Surface.Presentation.Controls.SurfaceMenuItem | yes | Removed because touch functionality is now inherited from .NET 4. | ||
| yes | yes | Updated to include a new property, SecurePassword, to obtain a password in encrypted format. | ||
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. Additionally, the IsPanningEnabled property has been removed. Use IsManipulationEnabled instead. | |
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | ||
| Microsoft.Surface.Presentation.Controls.SurfaceUserControl | yes | Removed because touch functionality is now inherited from .NET 4. Use UserControl instead. | ||
| yes | yes | yes | Updated. All contact-related members have been removed because touch (and mouse) functionality is now inherited from UIElement. | |
| yes | yes | Updated to reflect the new generic tag format. The Matches method has changed to use the InputDevice class. A new property, IsPhysicalScalingEnabled, has been added. TrackedContact was renamed to TrackedTouch. The class now uses IManipulator. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| yes | yes | Replaces the ByteTagVisualizationDefinition and IdentityTagVisualizationDefinition class because of the new generic tag format. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| yes | yes | Updated to reflect the new generic tag format. GetVisualizationForContact has been renamed to GetVisualizationForInput and uses the InputDevice class. GetOrientation and GetPosition have been changed to take a UIElement object. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| yes | yes | Updated to reflect the new generic tag format. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. CreateVisualizationForTag has been changed to take a UIElement object. Touch (and mouse) functionality is now inherited from UIElement. | ||
| yes | yes | Added. Classes have been moved from the ContactVisualizations namespace and renamed to maintain naming parity with the new .NET 4 touch functionality that is now used by Presentation layer applications. | ||
| Microsoft.Surface.Presentation.Controls.TouchVisualizations. TouchVisualizerRectangleAdapter | yes | yes | Renamed to Microsoft.Surface.Presentation.Controls.TouchVisualizations.RectangleTouchVisualizerAdapter to be consistent with other visualizer adapters. | |
| Microsoft.Surface.Presentation.IContactInputElement.CaptureContact | yes | Removed. Use the CaptureTouch method instead. Touch functionality is now included in .NET 4, in the System.Windows.Input namespace. Extra functionality is provided by the SurfaceTouchExtensions class. | ||
| Microsoft.Surface.Presentation.IdentityTag | yes | Removed. Byte tags and identity tags have been replaced by a more generic tag type, defined in the TagData structure. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| yes | Added to be used by the InteractiveSurfaceDevice class to obtain information when the hardware capabilities of the interactive surface device change. | |||
| yes | yes | Added to be used by the TouchExtensions class to obtain data about the size and orientation of an input relative to an element. | ||
| yes | yes | Moves from the Microsoft.Surface.Presentation namespace. | ||
| yes | yes | Moved from the Microsoft.Surface.Presentation namespace. Many members have been added to this class to detect hardware capabilities and obtain data about interactive surface device bounds. | ||
| yes | Moved from the Microsoft.Surface.Presentation namespace, and updated to support the new generic tag format. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | |||
| yes | Added to represent a given value in the new TagData structure. TagValue is used in tag matching methods when wildcard values might be used. | |||
| yes | Added and used internally to convert tag values to and from strings. | |||
| yes | Added to provide special touch functionality to Surface applications, such as reporting tap and hold gestures, tag recognition, input orientation, and capturing multiple input devices. Most of the touch functionality available to Surface applications is included in .NET 4, in the System.Windows.Input namespace. Surface controls inherit most of their touch functionality from UIElement. | |||
| Microsoft.Surface.Presentation.InteractiveSurface | yes | Moved to the Microsoft.Surface.Presentation.Input namespace. | ||
| Microsoft.Surface.Presentation.InteractiveSurfaceDevice | yes | Moved to the Microsoft.Surface.Presentation.Input namespace. Many members have been added to detect hardware capabilities and obtain data about device bounds. | ||
| Microsoft.Surface.Presentation.IntermediateContact.BoundingRect | yes | Removed. Touch functionality is now included in .NET 4, in the System.Windows.Input namespace. Surface controls now inherit most of their touch functionality from UIElement. | ||
| Microsoft.Surface.Presentation.Manipulations | yes | Removed. Manipulation functionality has been added to .NET 4. You must manually convert your code to use the System.Windows.Input.Manipulations namespace. | ||
| yes | Added to provide classes that define each of the four Surface color schemes, one of which is selected by the Surface administrator. For more information, see Surface Colors and Palettes. | |||
| yes | Added to provide access to the color scheme being used by your application. The Surface administrator can select from four color schemes. For more information, see Surface Colors and Palettes. | |||
| yes | yes | yes | Updated with new members (CanRotate, CanScale). Additionally, GetOrientation and GetPosition now use IInputElement instead of UIElement. | |
| yes | yes | yes | Updated. The BeginDragDrop method signature has changed to use the InputDevice class. The other members of this class have been updated to use SurfaceDragCursor instead of FrameworkElement. | |
| yes | Added to provide access to a palette of colors that represents the color scheme being used by your application. For more information, see Surface Colors and Palettes. | |||
| Microsoft.Surface.Presentation.TagData | yes | Moved to the Microsoft.Surface.Presentation.Input namespace. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| Microsoft.Surface.Presentation.TagType | yes | Removed because of the new generic tag format, defined by the TagData structure. You must manually update your code and the tag definitions in your application registration XML file, and you must register tag objects using the new XML format instead of registering tags in the registry. | ||
| yes | Added to be used by the InteractiveSurfaceDevice class to work with hardware that is capable of reporting tilt values, such as devices made for Surface. | |||
| yes | Added to be used by the ApplicationServices class to obtain the session identifier. | |||
| yes | Added to be used by the ApplicationServices class to provide information about why an application is shutting down. | |||
| Microsoft.Surface.Simulator.Automation | yes | Removed because the new Input Simulator tool cannot be automated directly. However, the Surface Stress Tool uses Input Simulator to generate input. You can use the Surface Stress tool in parameterized mode (with a configuration file) to achieve a result similar to automating the Input Simulator tool. For more information, see Running Surface Stress in Parameterized Mode. | ||
| yes | Added to provide information about the availability of the Surface environment and input. | |||
| yes | Replaces the Microsoft.Surface.Core.SurfaceKeyboard class. | |||
| Microsoft.Surface.Tools.IdentityTagGenerator | yes | Removed because of the new generic tag format. For information about printing tags, see Printing Tags. | ||
| yes | yes | Updated. New overloads of the RequestNotification method have been added. | ||
| yes | Added to define different application states for the new WindowAvailability property. |
© Microsoft Corporation. All rights reserved.
