Table of Contents

• Overview
  • Samples That Use the Presentation Layer
  • Microsoft Surface 1.0 SP1: SDK - Code Sample Applications

    Table of Contents

    • Overview
      Samples That Use the Core Layer and the XNA Framework
      • Samples That Use the Surface Shell API
      • Installing the Samples
    • Activate Application from an Application
      • API Concepts Exposed
    • Attract Application
      • API Concepts Exposed
    • Cloth
      • API Concepts Exposed
    • Controls Box
      • API Concepts Exposed
    • Data Visualizer
      • API Concepts Exposed
    • Finger Fountain
      • API Concepts Exposed
    • Fractal Browser
      • API Concepts Exposed
    • Grand Piano
      • API Concepts Exposed
    • Item Compare
      • API Concepts Exposed
      • Constructing Tagged Objects to Use with This Sample Application
      • Starting the Item Compare Sample Application
    • Notifications
      • API Concepts Exposed
    • Paddle Ball
      • API Concepts Exposed
    • Photo Paint
      • API Concepts Exposed
    • RawImage Visualizer
      • API Concepts Exposed
      • Binarized and Normalized Images
      • Image Rendering
    • ScatterPuzzle
      • API Concepts Exposed
    • Shopping Cart
      • API Concepts Exposed
    • Tag Visualizer Events
      • API Concepts Exposed
    • XNA Scatter
      • API Concepts Exposed

    Overview

    The Microsoft Surface SDK contains the following samples:
     

    Samples That Use the Presentation Layer

    • Controls Box shows how to build simple application behavior, such as updating a text box when a user touches a button, from touch-enabled controls that the Presentation layer provides.
      
      
    • Data Visualizer shows contact properties that are exposed in the Presentation layer (such as x, y, height, width, major, minor axis, and orientation) and how you can read and use these properties in a Microsoft Surface application.
      
      
    • Fractal Browser displays an H-fractal. A user can zoom the image to be larger than the Microsoft Surface screen and can rotate and pan the content.
      
      
    • Grand Piano demonstrates how to integrate sound into Microsoft Surface applications Presentation Layer
      • Controls Box shows how to build simple application behavior, such as updating a text box when a user touches a button, from touch-enabled controls that the Presentation layer provides.
        
        
      • Data Visualizer shows contact properties that are exposed in the Presentation layer (such as x, y, height, width, major, minor axis, and orientation) and how you can read and use these properties in a Microsoft Surface application.
        
        
      • Fractal Browser displays an H-fractal. A user can zoom the image to be larger than the Microsoft Surface screen and can rotate and pan the content.
        
        
      • Grand Piano demonstr based on the Presentation layer.
        
        
      • Item Compare represents a simple tool that lets a user compare and contrast the properties of two "items" (tagged objects).
        
        
      • Paddle Ball uses WPF controls to implement contact tracking and movable user interface elements as part of a four-person game.
        
        
      • Photo Paint uses the SurfaceInkCanvas control to implement drawing and painting over pictures and video.
        
        
      • ScatterPuzzle shows an implementation of the ScatterView and SurfaceListBox controls to create a simple puzzle game. The ScatterView and SurfaceListBox controls automatically provide some powerful Microsoft Surface-related features.
        
        
      • Shopping Cart shows how to implement drag-and-drop functionality in a retail application.
        
        
      • Tag Visualizer Events shows how to incorporate hit-testing in the TagVisualizer control to let UI elements react when tagged objects move over them.
        
        

      Samples That Use the Core Layer and the XNA Framework

      • Finger Fountain draws small images for every contact at every frame. This sample emphasizes multiple touches and shows how to use the Microsoft XNA APIs.
        
        
      • Cloth is an XNA-based application that demonstrates how to use the Core Interaction Framework.
        
        
      • RawImage Visualizer shows how to use the RawImage APIs for XNA applications. This sample displays captured normalized (8 bit per pixel) images that are flipped vertically.
        
        
      • XNA Scatter demonstrates how to use the manipulations and inertia APIs to move graphical user interface (GUI) components in a Microsoft Surface application around in a natural and intuitive way.
        
        

      Samples That Use the Surface Shell API

      • Activate Application from an Application demonstrates how to activate one application from another Microsoft Surface application.
        
        
      • Attract Applications demonstrates a basic Microsoft Surface Attract Applications, including the necessary XML file needed to register as an attract application.
        
        
      • Notifications demonstrates how to display messages to the user, whether your application is currently active or is running in the background.
        
        

      Installing the Samples

      The samples are included in the Surface Code Samples.zip file that is installed into the %ProgramFiles%\Microsoft SDKs\Surface\v1.0\Samples folder. A link to this ZIP file also appears on the Start menu under Microsoft Surface SDK 1.0 SP1 -> Samples. Extract the contents of ZIP file to a directory where you have write permissions.

      A batch file called InstallSamples.bat is included in the ZIP file. In Windows Explorer, right-click the batch file, and then click Run as administrator. The batch file builds each SDK sample and creates the XML file needed to register the application with Surface Shell. It then copies the XML file to the correct directory so it will show up in Launcher.

      After the batch file is finish, do one of the following:

      • On a Microsoft Surface unit: Start Surface Shell by using the desktop shortcut. Browse the samples by using Launcher. If the samples are in a public directory (that is, any user can access them on the system), samples will also be available in user mode.
        
        
      • On a computer: Start Surface Simulator and use Launcher to browse the samples.

      If the batch file fails, check to see that it is not being run directly from the ZIP directory and that it is being run as administrator. Alternatively, open SDKSamples.sln in Microsoft Visual C# 2008 Express Edition (or Microsoft Visual Studio 2008) and install the built samples manually to the Surface Shell.
       

      Activate Application from an Application

      This sample demonstrates how to activate one application from another Microsoft Surface application.

      

     

    API Concepts Exposed

    This sample shows how to:

    • Launch another application from your application
      
      
    • Set the orientations of the application being launched.

    Attract Application

    This sample demonstrates a basic Microsoft Surface attract application, including the necessary XML file and registry entries needed to register as an attract application.
     

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Disable keyboard input.
      
      
    • Handle mouse and touch input.

    Cloth

    The Cloth sample application is a Microsoft XNA-based application that demonstrates how to use the Core Interaction Framework.
     

     
     
    
    
    
    

    API Concepts Exposed

    This sample shows how to use the following Core Interaction Framework state machines:

    • ScrollViewerStateMachine
      
      
    • ListBoxStateMachine
      
      
    • ScrollBarStateMachine
      
      
    • ButtonStateMachine
      
      

    It also demonstrates the following animations:

    • Scroll bar thumb
      
      
    • List box
      
      
    • Scroll bar slide and fade
      
      
    • Item and bIC357318.jpg" /> 
       
      
      
      
      

      API Concepts Exposed

      This sample shows how to use the following Core Interaction Framework state machines:

      • ScrollViewerStateMachine
        
        
      • ListBoxStateMachine
        
        
      • ScrollBarStateMachine
        
        
      • ButtonStateMachine
        
        

      utton glow and grow
      
      

    The key classes from the Core Interaction Framework are UIController and UIElementStateMachine. The key classes from the XNA Framework are Game, GameComponentCollection, and DrawableGameComponent. The key class of the Cloth sample is the UIElement class, which derives from DrawableGameComponent and encapsulates a UIElementStateMachine object.

    Controls Box

    The Controls Box sample application shows how to create a touch-enabled user interface for a Microsoft Surface application with minimal code.
     

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Use the Presentation layer to create a user interface.
      
      
    • Use C# code to add logic to event handlers.
      
      
    • Use Microsoft Surface versions of button, check box, and slider controls to accept touch input.
      
      
    • Respond to events that the Microsoft Surface controls generate.
      
      
    • Use localization for one or more supported languages.
      
      

    You can add extra controls to this sample application by using Microsoft Expression Blend 2. You can also use Expression Blend 2 to view the XAML and C# code.
     

    Data Visualizer

    The Data Visualizer sample application demonstrates how to use the Presentation layer of the Microsoft Surface SDK to display a visual representation of and the geometric attributes for every contact on a Microsoft Surface unit.
     

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Parse Microsoft Surface contacts and how to access Microsoft Surface contact attributes.
      
      
    • Track multiple contacts, sort them, and render information that is based on those contacts.
      
      
    • Use multiple classes to represent groups of user interface elements. You can use multiple classes in this way by including a user control as a child element of another user interface element. The control and its elements are packaged separately, so the user control is versatile and modular.
      
      
    • Read data from a Contact object. Contacts have properties that you can directly access. The Data Visualizer application reads the X and Y positions of contacts and uses that information to position corresponding ellipses.
      
      
    • Update user interface elements that are relative to contacts. User interface elements (UIElement) in the Data Visualizer application are positioned by using data that the application gets from contacts. The application updates ellipses in relation to contact position and removes ellipses from rendering when a contact is removed from the Microsoft Surface screen. This is also true of the bounding rectangles if that option is selected.

    Finger Fountain

    The Finger Fountain sample application displays small images when it receives a Microsoft Surface contact event. Each image then shrinks and finally disappears after a certain amount of time passes.

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Build basic Microsoft XNA rendering functionality and connect it to multitouch Microsoft Surface applications. An XNA application must use the Core layer to provide Microsoft Surface touch functionality.
      
      
    • Enable Microsoft Surface input in an XNA application. The XNA framework includes an overrideable Initialize function. From this function, the Finger Fountain sample calls the InitializeSurfaceInput method to enable Microsoft Surface input.
      
      
    • Obtain a contact collection. The sample's Update method overrides the XNA Game.Update method. The sample obtains a snapshot of the current contacts in this overridden Update method.
      
      
    • Insert sprites at the position of a contact. The sample reviews each contact in the contact collection, determines what type of contact exists, and draws a sprite where it is appropriate.

     

    Fractal Browser

    The Fractal Browser sample application displays an H-fractal. A user can zoom the image to be larger than the MiInitializeSurfaceInput  
     
    

    API Concepts Exposed

    This sample shows how to:

    • Implement manipulations on a single piece of content.
      
      
    • Apply inertia to every manipulation.
      
      
    • Incorporate non-scaling items on a zoomable piece of content.
      
      
    • Implement Microsoft Surface user experience guidelines about zooming and panning content while adhering to the higher philosophy of a multiuser experience.

    Grand Piano

    The Grand Piano sample demonstrates how to integrate sound into Microsoft Surface applications based on the Presentation layer.

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Integrate sound with controls by using XACT, a cross-platform audio creation tool shipped as part of Microsoft XNA Game Studio 2.0.
      
      
    • Use audio files for each key's sound in the wave bank in XACT.
      
      
    • Build a multitouch experience by using simple Microsoft Windows Presentation Foundation (WPF) controls.
      
      
    • Produce simultaneous and overlapping sounds when multiple keys are pressed.
      
      
    • Have a note continue to play while the corresponding key is pressed.
      
      
    • Associate a key's sound with an audio Cue that can be called from a Microsoft XNA or WPF application.

    Item Compare

    The Item Compare sample application represents a simple tool that lets a user compare and contrast the properties of two "items" (tagged objects). The items could be anything—different products for sale in a store, business cards for different companies, or anything else where a user might want to compare one thing with another.

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Work with the TagVisualizer control.
      
      
    • Read configuration information at run time to control the behavior of TagVisualizer.
      
      
    • Use multiple TagVisualization objects to move and resize a user control, by using the Affine2DManipulationProcessor class.
      
      
    • Design an intuitive and compelling user experience for an application that works with tagged objects.
      
      
    • Make a tag-driven application work with the Surface Shell’s object routing feature.
      
      

    You can place a tagged object on this sample application. If you configure the application to recognize the tag value (by using the XML file that is included with the sample), the application shows information about the object (which is also configured in the XML file).

    If you place a second tagged object on the application, it shows a table that enables side-by-side comparison of the two objects. You can move and resize the table by moving the tagged objects.

    The Item Compare sample application is a sample of a tag-driven application for Microsoft Surface. For more information about how to design a tag-driven application, see Designing Tag-Driven Applications for Microsoft Surface.
     

    Constructing Tagged Objects to Use with This Sample Application

    You must construct your own tagged objects to work with the Item Compare application. Item Compare gives you complete run-time control over the physical configuration of the tagged objects, but the default configuration that is included with the sample application assumes a particular object shape, tag placement, and set of tag values.

    Because the Item Compare application distinguishes only a relatively small number of objects, this sample application uses byte tags instead of identity tags. (For more information about choosing between byte tags and identity tags, see Tagged Objects.) However, you can modify this application to use identity tags instead of byte tags by following the comments in the application's source code that identify where you must modify the code to use identity tags instead.

    Item Compare assumes that a tagged object is the same size and shape as a standard business card: a rectangle that is 3.5 inches wide and 2 inches high. The application also assumes that the byte tag is located in the center of the card. The following illustration shows the back of the card with the byte tag in the proper position and orientation. The label (1) denotes the three white guide circles of the byte tag.

    

    By default, Item Compare recognizes three byte tag values: 0xC1, 0xC2, and 0xC3.

    Starting the Item Compare Sample Application

    The Item Compare sample is integrated with the Surface Shell’s object routing feature. When you install the Microsoft Surface SDK sample applications, the installation batch file completes the necessary steps to integrate the Item Compare application work with object routing.

    able>

    Important
    Object routing involves installing certain registry keys. For simplicity with the Item Compare sample application, Item Compare uses a .reg file to install the required registry keys. However, we recommend that you do not use .reg files for a production-quality application. A .reg file does not handle common installation scenarios, such as duplicating existing registry keys, safely removing keys when an application is uninstalled, and so on. For more information about how to set up your application’s installer to work with object routing, see Specifying Physical Attributes of Tagged Objects.
    Important
    Object routing involves installing certain registry keys. For simplicity with the Item Compare sample application, Item Compare uses a .reg file to install the required registry keys. However, we recommend that you do not use .reg files for a production-quality application. A .reg file does not handle co

      

    Notifications

    The Notifications sample demonstrates how to display messages to the user, whether your application is currently active or is running in the background.

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Display a notification immediately.
      
      
    • Display a notification when your application is not in the foreground.
      
      
    • Set the level of the notification, which dictates how long it is displayed on the screen.

    Paddle Ball

    The Paddle Ball sample application shows how to use Microsoft Surface multitouch capability to enable up to four users to participate in a game simultaneously.

     
     
    

    API Concepts Exposed

    This sample application shows how to:

    • Access the Presentation layer of the Microsoft Surface SDK to build multitouch applications.
      
      
    • Use routed events to track contacts.
      
      
    • Use SurfaceUserControl to create touch sensitive, reusable custom controls.
      
      
    • Link event handlers to user interface elements. The Paddle Ball application uses Microsoft Windows Presentation Foundation (WPF) to capture contact information. Each paddle handles the ContactUp, ContactDown, and ContactChanged events. This functionality is defined in the XAML file.
      
      
    • Capture contacts. Capturing contacts is important to connect individual contacts to a specified user interface element. When the application captures a contact, it sends routed events to the user interface element that captured the contact. The paddle then receives all relevant contact messages even if the contact moves off of the paddle.
      
      
    • Use captured contacts inside event handlers. A captured contact raises a ContactChanged event and the application updates the paddle's position.

    Photo Paint

    The Photo Paint sample demonstrates some of the user scenarios made possible by using the SurfaceInkCanvas control. Some of these include using your fingers to write, draw, erase, paint over photos, and so on.

     
     
    

    API Concepts Exposed

    This sample shows how to use the SurfaceInkCanvas control to:

    • Render the path taken by a moving contact.
      
      
    • Lay a SurfaceInkCanvas control over a photo or image so you can render digital ink over the content.
      
      
    • Change the height and width of the ink stroke based on the size of the contact as its physical area changes over time.
      
      
    • Record strokes and play them back over time.
      
      
    • Produce a stroke of constant thickness.
      
      
    • Switch between drawing, manipulating, and erasing modes.

    RawImage Visualizer

    The RawImage Visualizer sample application demonstrates how to use RawImage APIs for Microsoft Surface applications that use the Microsoft XNA development platform. This sample application displays captured normalized (8 bit per pixel) images that are flipped vertically.

     
     
    

    API Concepts Exposed

    This sample application demonstrates how to:

    • Use the TryGetRawImage and UpdateRawImage APIs.
      
      
    • Use the Texture2D and SpriteBatch methods to render normalized raw images.
      
      

    Binarized and Normalized Images

    You can retrieve two types of images by using the RawImage APIs:

    • A binarized image is 1 bit per pixel, so it is very compact. A binarized image is more useful to recognize objects than a normalized image.
      
      
    • A normalizedul>
    • Use the TryGetRawIm image is 8 bits per pixel. A normalized image is useful for rendering inside the XNA framework.
      
      

    Image Rendering

    This sample application captures every frame of RawImage, scales the image, and flips the image vertically before it renders the image. The image is flipped vertically so it does not obscure an image from behind a contact.
     

    ScatterPuzzle

    The ScatterPuzzle sample application shows an implementation of the ScatterView and SurfaceListBox controls to create a simple puzzle game. The ScatterView and SurfaceListBox controls automatically provide some powerful Microsoft Surface-related features.

     
     
    

    API Concepts Exposed

    This sample application demonstrates how to:

    • Load items into a ScatterView or SurfaceListBox control.
      
      
    • Turn off selected manipulations by using the AllowedManipulations property and have flexibility to decide how the user can interact with the ScatterView controls.
      
      
    • Use the large number of features that are included with the ScatterView and SufaceListBox controls. These features include manipulations such as Flick, Rotate, and Move and predefined VisualEffects.
      
      
    • Use the ManipulationCompleted event to evaluate the application's state after a ScatterViewItem has been manipulated.
      
      
    • Use a non-rectangular ScatterViewItem.
      
      
    • Restyle a ScatterViewItem to use a custom shadow shape.
      
      
    • Apply custom visuals to a ScatterViewItem control.
      
      
    • Animate a ScatterViewItem control.
      
      
    • Combine the content of multiple ScatterViewItem objects into one larger ScatterViewItem object.
      
      
    • Detect when two ScatterViewItem objects are adjacent.

    Shopping Cart

    The Shopping Cart sample application shows how to implement drag-and-drop functionality in a retail application.

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Drag elements out of a list.
      
      
    • Drag elements into a ScatterView control.
      
      
    • Use a LibraryStack control that users can flick and drag items into.
      
      
    • Use a LibraryStack control to implement a checkout mechanism.
      
      
    • Use an on-screen keyboard for text input. Place a 0xC0 tag on the main ScatterView object to open a password entry TagVisualization, and then touch the text box to open the keyboard. For more information about the keyboard and keypad, see Keyboard and Numeric Keypad.
      
      
    • Move items between ScatterView controls that are siblings to or parents or children of each other.
      
      
    • Use the TagVisualizer control to recognize tagged objects.
      
      
    • Create a continuously scrolling list. You can scroll the content forever, and the list items appear to loop around from the end of the list to the front.
      
      

    You can drag items, one or more at a time, to the gray canvas from the list. You can also resize, rotate, or move the ScatterViewItem controls.
     

    Tag Visualizer Events

    The Tag Visualizer Events sample application shows how to implement hit-testing functionality to allow UI elements to react when tagged objects move over them.

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Use the TagVisualizer control to recognize tagged objects.
      
      
    • Make UI elements react when tagged objects move over them. This behavior works regardless of whether the tagged object moves over the UI element, or the UI element moves under the tagged object.
      
      
    • Make TagVisualization controls react when they move over other UI elements.
      
      
    • Encapsulate the above functionality in a reusable, XAML-friendly class that's portable between applications.
      
      

    You can place any tagged object on the application, which will display a red "glow" visualization around the tag. When the tagged object moves over one of the UI elements in the application, the visualization reacts (becomes smaller and partially transparent), as does the UI element (which shows a red highlight).
     

    XNA Scatter

    The XNA Scatter sample demonstrates how to use the manipulation and inertia processors in a Microsoft XNA application.

     
     
    

    API Concepts Exposed

    This sample shows how to:

    • Track the relative movements of a group of contacts.
      
      
    • Translate, rotate and scale a user interface object by tracking contacts over the object.
      
      
    • Apply inertia processing to show a user interface object sliding across the screen from being flicked by the user.
      
      
    • Resize user interface objects by stretching them with two fingers.
      
      

    This sample implements behavior that is similar to the ScatterView control but in an XNA application.