Developing an end-to-end Windows Store app using C++ and XAML: Hilo David Britch Bob Brumfield Colin Campbell Scott Densmore Thomas Petchel Rohit Sharma Blaine Wastell November 2012 2 This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes. © 2012 Microsoft Corporation. All rights reserved. Microsoft, DirectX, Expression, Silverlight, Visual Basic, Visual C++, Visual Studio, Win32, and Windows are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners. 3 Contents Developing an end-to-end Windows Store app using C++ and XAML: Hilo 12 Applies to 12 Download 12 Prerequisites 12 Table of contents at a glance 13 Why XAML? 13 Learning resources 14 Getting started with Hilo (Windows Store apps using C++ and XAML) 15 Download 15 Building and running the sample 15 Projects and solution folders 17 The development tools and languages 17 Designing Hilo's UX (Windows Store apps using C++ and XAML) 19 You will learn 19 Deciding the UX goals 19 Brainstorming the user experience 20 What's Hilo great at? 20 Deciding the app flow 20 Deciding what Windows 8 features to use 22 Other features to consider 23 Deciding how to sell the app 23 Making a good first impression 23 Prototyping and validating the design 24 Writing modern C++ code in Hilo (Windows Store apps using C++ and XAML) 25 You will learn 25 Download 25 Understanding the app's environment 25 The package manifest 27 4 C++ standard libraries 29 Windows Runtime libraries 29 Win32 and COM API 30 Parallel Patterns Library (PPL) 31 XAML 31 Visual Studio project templates 31 C++ language extensions for interop 32 The C++ compiler and linker 32 Certification process of the Windows Store 32 Deployment 33 Using C++11, standard C++ libraries, and a modern coding style 33 Lambda expressions 33 Stack semantics, smart pointers, and RAII 33 Automatic type deduction 33 Range-based for loops 34 Standard algorithms and containers 34 Free-form iterators 36 The pimpl idiom 36 Exception handling 38 Adapting to async programming 39 Using parallel programming and background tasks 42 Tips for using C++/CX as an interop layer 47 Be aware of overhead for type conversion 48 Call methods of ref classes from the required thread 49 Mark destructors of public ref classes as virtual 49 Use ref classes only for interop 50 Use techniques that minimize marshaling costs 50 Use the Object Browser to understand your app's .winmd output 50 If C++/CX doesn't meet your needs, consider WRL for low-level interop 51 Don't confuse C++/CX language extensions with C++/CLI 51 Don't try to expose internal types in public ref classes 52 5 Tips for managing memory 52 Use smart pointers 52 Use stack semantics and the RAII pattern 54 Don't keep objects around longer than you need 54 Avoid circular references 56 Debugging tips and techniques 58 Use breakpoints and tracepoints 58 Use OutputDebugString for "printf" style debugging 59 Break when exceptions are thrown 59 Use the parallel debugging windows 59 Use the simulator and remote debugging to debug specific hardware configurations 59 Porting existing C++ code 60 Overview of the porting process 61 Compile and test the code on Windows 8 61 Identify unsupported library functions 61 Use functions from the Window Runtime API reference 62 Replace synchronous library functions with async versions 62 Convert long running operations in your code to async versions 62 Validate the package with the Windows App Certification Kit 63 Overview of supported functions 63 Porting from Win32-based UI 63 Porting DirectX 63 Porting MFC 63 Using the C++ run-time library (CRT) 64 Using the C++ Standard Library 64 Using ATL 64 Porting guidance 65 Port all existing code, including libraries 65 Link to static libraries or import libraries as usual 65 Use C++/CX or WRL if your library needs to invoke Windows Runtime functions 66 Use reg-free COM for activation 66 6 Convert to Windows Runtime types when marshaling cost is an issue 66 Decide between using wrapper code and converting existing code 66 For more info about porting 67 Async programming patterns and tips in Hilo (Windows Store apps using C++ and XAML) 68 You will learn 68 Ways to use the continuation chain pattern 68 Value-based and task-based continuations 70 Unwrapped tasks 70 Allowing continuation chains to be externally canceled 71 Other ways of signaling cancellation 75 Canceling asynchronous operations that are wrapped by tasks 75 Using task-based continuations for exception handling 76 Assembling the outputs of multiple continuations 77 Using nested continuations for conditional logic 79 Showing progress from an asynchronous operation 80 Creating background tasks with create_async for interop scenarios 81 Dispatching functions to the main thread 81 Using the Asynchronous Agents Library 82 Tips for async programming in Windows Store apps using C++ 82 Don’t program with threads directly 83 Use "Async" in the name of your async functions 83 Wrap all asynchronous operations of the Windows Runtime with PPL tasks 83 Return PPL tasks from internal async functions within your app 84 Return IAsyncInfo-derived interfaces from public async methods of public ref classes 84 Use public ref classes only for interop 84 Use modern, standard C++, including the std namespace 84 Use task cancellation consistently 85 Handle task exceptions using a task-based continuation 86 Handle exceptions locally when using the when_all function 86 Call view model objects only from the main thread 88 Use background threads whenever possible 88 7 Don't call blocking operations from the main thread 88 Don't call task::wait from the main thread 89 Be aware of special context rules for continuations of tasks that wrap async objects 89 Be aware of special context rules for the create_async function 89 Be aware of app container requirements for parallel programming 90 Use explicit capture for lambda expressions 90 Don't create circular references between ref classes and lambda expressions 90 Don't use unnecessary synchronization 91 Don't make concurrency too fine-grained 91 Watch out for interactions between cancellation and exception handling 91 Use parallel patterns 91 Be aware of special testing requirements for asynchronous operations 91 Use finite state machines to manage interleaved operations 92 Working with tiles and the splash screen in Hilo (Windows Store apps using C++ and XAML) 95 You will learn 95 Why are tiles important? 95 Choosing a tile strategy 95 Designing the logo images 96 Placing the logos on the default tiles 97 Updating tiles 97 Adding the splash screen 104 Using the Model-View-ViewModel (MVVM) pattern in Hilo (Windows Store apps using C++ and XAML) 106 You will learn 106 What is MVVM? 106 MVVM in Hilo 107 Why use MVVM for Hilo? 109 For more info 109 Variations of the MVVM pattern 109 Mapping views to UI elements other than pages 109 Sharing view models among multiple views 109 8 Executing commands in a view model 110 Using a view model locator object to bind views to view models 111 Tips for designing Windows Store apps using MVVM 111 Keep view dependencies out of the view model 112 Centralize data conversions in the view model or a conversion layer 112 Expose operational modes in the view model 112 Ensure that view models have the Bindable attribute 113 Ensure that view models implement the INotifyProperyChanged interface for data binding to work 113 Keep views and view models independent 115 Use asynchronous programming techniques to keep the UI responsive 115 Always observe threading rules for Windows Runtime objects 115 Using the Repository pattern in Hilo (Windows Store apps using C++ and XAML) 117 You will learn 117 Introduction 117 Code walkthrough 119 Querying the file system 120 Detecting file system changes 121 Creating and navigating between pages in Hilo (Windows Store apps using C++ and XAML) 124 You Will Learn 124 Understanding the tools 124 Adding new pages to the project 125 Creating pages in the designer view 126 Establishing the data binding 128 Adding design time data 129 Creating the main hub page 130 Navigating between pages 132 Supporting portrait, snap, and fill layouts 133 Using controls in Hilo (Windows Store apps using C++ and XAML) 137 You will learn 137 Data binding 138 9 Data converters 138 Common controls used in Hilo 142 Image 142 Grid and GridView 144 ProgressRing 148 Button 149 TextBlock 150 AppBar 151 StackPanel 155 ListView 157 SemanticZoom 159 Canvas and ContentControl 159 Popup 162 Styling controls 162 UI virtualization for working with large data sets 162 Overriding built-in controls 163 Touch and gestures 167 Testing controls 167 Using touch in Hilo (Windows Store apps using C++ and XAML) 168 You will learn 168 Press and hold to learn 169 Tap for primary action 172 Slide to pan 175 Swipe to select, command, and move 176 Pinch and stretch to zoom 177 Turn to rotate 180 Swipe from edge for app commands 182 Swipe from edge for system commands 184 What about non-touch devices? 184 Handling suspend, resume, and activation in Hilo (Windows Store apps using C++ and XAML) 186 You will learn 186 10 Tips for implementing suspend/resume 186 Understanding possible execution states 187 Implementation approaches for suspend and resume in C++ and XAML 188 Code walkthrough of suspend 190 Code walkthrough of resume 193 Code walkthrough of activation after app termination 194 Other ways to exit the app 200 Improving performance in Hilo (Windows Store apps using C++ and XAML) 202 You will learn 202 Improving performance with app profiling 202 Profiling tips 203 Other performance tools 204 Performance tips 204 Keep the launch times of your app fast 204 Emphasize responsiveness in your apps by using asynchronous API calls on the UI thread 205 Use thumbnails for quick rendering 205 Prefetch thumbnails 205 Trim resource dictionaries 206 Optimize the element count 206 Use independent animations 206 Use parallel patterns for heavy computations 207 Be aware of the overhead for type conversion 207 Use techniques that minimize marshaling costs 207 Keep your app’s memory usage low when suspended 207 Minimize the amount of resources your app uses by breaking down intensive processing into smaller operations 208 Testing and deploying Windows Store apps: Hilo (C++ and XAML) 209 You will learn 209 Ways to test your app 209 Using the Visual Studio unit testing framework 210 Using Visual Studio to test suspending and resuming the app 211 [...]... Windows App Certification Kit 216 Creating a Windows Store certification checklist 216 Meet the Hilo team (Windows Store apps using C+ + and XAML) 218 About patterns & practices 218 Meet the team 218 12 Developing an end- to -end Windows Store app using C+ + and XAML: Hilo The Hilo end- to -end photo sample provides guidance to C+ + developers that want to. .. std::vector object as its argument In other words, you can keep your old vector data and create a new Platform::Collections::Vector instance with a copy of the original data As another example, Hilo uses std::iota and std::random_shuffle to choose random photos (more precisely, indices to an array of photos) This example uses std::iota to create a sequence of array indices and std::random_shuffle to randomly... (Modern C+ +) first If you're new to C+ +/CX, read Visual C+ + Language Reference (C+ +/CX) You will learn     When to use standard C+ + types and libraries in Windows Store apps Best practices for using C+ +/CX How to port existing C+ + libraries for use by Windows Store apps Recommended debugging techniques using Visual Studio Download Understanding the app' s environment Windows Store apps, such as Hilo,... notifications or secondary tiles, you can learn about them by reading Guidelines and checklist for secondary tiles and Guidelines and checklist for toast notifications Touch first Touch is more than simply an alternative to using the mouse because it can add a personal connection between the user and the app We wanted to make touch a first-class part of the app For example, touch is a very natural way to. .. Store apps and Blend for Visual Studio for user experience guidelines that can help you create a great Windows Store app The document Designing Hilo's UX explains how we designed the Hilo UX 15 Getting started with Hilo (Windows Store apps using C+ + and XAML) Here we explain how to build and run the Hilo Windows Store app, how the C+ + and XAML source code is organized, and what tools and languages it... design and core app logic Note Just because we didn't use DirectX in our app doesn't mean it won't work for yours If you prefer DirectX or your app or game has specific requirements or cannot be written in XAML or JavaScript, see Developing games You can also use XAML and DirectX together in your Windows Store app There are two approaches You can add XAML to a DirectX app, or you can include DirectX surfaces... randomly rearrange the sequence 36 C+ +: RandomPhotoSelector.cpp vector RandomPhotoSelector::CreateRandomizedVector(unsigned int vectorSize, unsigned int sampleSize) { // Seed the rand() function, which is used by random_shuffle srand(static_cast(time(nullptr))); // The resulting set of random numbers vector result(vectorSize); // Fill with [0 vectorSize) iota(begin(result),... the C+ + project templates for Windows Store apps Certification process of the Windows Store Publishing to the Windows Store makes your app available for purchase or free download Publishing to the store is optional Apps in the store must undergo a certification process that includes an automated structural check For a description of Hilo's certification experience, see Testing and deploying the app. .. IVector, has an overloaded constructor that takes an rvalue reference to a std::vector To call the overloaded constructor, use the std::move function or directly pass the result of a function that returns std::vector For an example that shows this pattern, see Collections (C+ +/CX) Note You don't have to use move semantics The Platform::Collections::Vector class includes a standard copy constructor... Windows Store apps using C+ + and XAML, including how to adapt to asynchronous programming using the Parallel Patterns Library (PPL) They arose from questions we ourselves asked as we started developing Hilo C+ + Windows Store apps using C+ + combine the best features of C+ +11, the modern C+ + coding style, and C+ +/CX If you're new to C+ +11, consider reading C+ +11 Features (Modern C+ +) and Welcome Back to C+ + . Developing an end- to -end Windows Store app using C+ + and XAML: Hilo The Hilo end- to -end photo sample provides guidance to C+ + developers that want to create a Windows 8 app using modern C+ +,. You can also use XAML and DirectX together in your Windows Store app. There are two approaches. You can add XAML to a DirectX app, or you can include DirectX surfaces in a XAML app. Which one to. (Windows Store apps using C+ + and XAML) Here we explain how to build and run the Hilo Windows Store app, how the C+ + and XAML source code is organized, and what tools and languages it uses.