Download Full Version ebook - Visit ebooknice.

com

(Ebook) Programming Windows Store Apps with HTML,

CSS, and JavaScript, Second Edition by Kraig
Brockschmidt ISBN 9780735672611, 073567261X

https://ebooknice.com/product/programming-windows-store-
apps-with-html-css-and-javascript-second-edition-5498638

Click the button below to download

DOWLOAD EBOOK

Discover More Ebook - Explore Now at ebooknice.com

 Instant digital products (PDF, ePub, MOBI) ready for you
Download now and discover formats that fit your needs...

Start reading on any device today!

(Ebook) Programming Windows Store Apps with HTML, CSS, and

JavaScript by Kraig Brockschmidt

https://ebooknice.com/product/programming-windows-store-apps-with-
html-css-and-javascript-11697606

ebooknice.com

(Ebook) Biota Grow 2C gather 2C cook by Loucas, Jason;

Viles, James ISBN 9781459699816, 9781743365571,
9781925268492, 1459699815, 1743365578, 1925268497
https://ebooknice.com/product/biota-grow-2c-gather-2c-cook-6661374

ebooknice.com

(Ebook) Matematik 5000+ Kurs 2c Lärobok by Lena

Alfredsson, Hans Heikne, Sanna Bodemyr ISBN 9789127456600,
9127456609
https://ebooknice.com/product/matematik-5000-kurs-2c-larobok-23848312

ebooknice.com

(Ebook) SAT II Success MATH 1C and 2C 2002 (Peterson's SAT

II Success) by Peterson's ISBN 9780768906677, 0768906679

https://ebooknice.com/product/sat-ii-success-
math-1c-and-2c-2002-peterson-s-sat-ii-success-1722018

ebooknice.com
(Ebook) Cambridge IGCSE and O Level History Workbook 2C -
Depth Study: the United States, 1919-41 2nd Edition by
Benjamin Harrison ISBN 9781398375147, 9781398375048,
1398375144, 1398375047
https://ebooknice.com/product/cambridge-igcse-and-o-level-history-
workbook-2c-depth-study-the-united-states-1919-41-2nd-edition-53538044

ebooknice.com

(Ebook) Building iPhone Apps with HTML, CSS, and

JavaScript: Making App Store Apps Without Objective-C or
Cocoa by Jonathan Stark ISBN 9780596805784, 0596805780
https://ebooknice.com/product/building-iphone-apps-with-html-css-and-
javascript-making-app-store-apps-without-objective-c-or-cocoa-1467236

ebooknice.com

(Ebook) Master SAT II Math 1c and 2c 4th ed (Arco Master

the SAT Subject Test: Math Levels 1 & 2) by Arco ISBN
9780768923049, 0768923042
https://ebooknice.com/product/master-sat-ii-math-1c-and-2c-4th-ed-
arco-master-the-sat-subject-test-math-levels-1-2-2326094

ebooknice.com

(Ebook) Building iphone apps with html, css, and

javascript: Making App Store Apps Without Objective-C or
Cocoa by Stark, Jonathan ISBN 9780596805784,
9781449382919, 9781449389000, 0596805780, 1449382916,
https://ebooknice.com/product/building-iphone-apps-with-html-css-and-
1449389007
javascript-making-app-store-apps-without-objective-c-or-cocoa-18480948

ebooknice.com

(Ebook) Building Android Apps with HTML, CSS, and

JavaScript by Jonathan Stark ISBN 9781449383268,
1449383262
https://ebooknice.com/product/building-android-apps-with-html-css-and-
javascript-1537242

ebooknice.com
PUBLISHED BY
Microsoft Press
A Division of Microsoft Corporation
One Microsoft Way
Redmond, Washington 98052-6399

Copyright © 2014 Microsoft Corporation

All rights reserved. No part of the contents of this book may be reproduced or tr ansmitted in any form or by any means
without the written permission of the publisher.

Microsoft Press books are available through booksellers and distributors worldwide. If you need support related to
this book, email Microsoft Press Book Support at mspinput@microsoft.com. Please tell us what you think of this
book at http://aka.ms/tellpress.

Unless otherwise noted, the companies, organizations, products, domain names, e -mail addresses, logos, people,
places, and events depicted in examples herein are fictitious. No association with any real company, organization,
product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under
copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any
purpose, without the express written permission of Microsoft Corporation.

Microsoft and the trademarks listed at http://www.microsoft.com/about/legal/en/us/IntellectualProperty/

Trademarks/EN-US.aspx are trademarks of the Microsoft group of companies. All other marks are property of their
respective owners.

This book expresses the author’s views and opinions. The information contained in this book is provided without any
express, statutory, or implied warranties. Neither the authors, Microsoft Cor poration, nor its resellers, or distributors will
be held liable for any damages caused or alleged to be caused either directly or indirectly by this book.

Acquisitions, Developmental, and Project Editor: Devon Musgrave

Cover: Twist Creative • Seattle and Joel Panchot

1
Table of Contents
Introduction ........................................................................................................................ 21
Who This Book Is For ........................................................................................................ 23
What You'll Need (Can You Say “Samples”?) ...................................................................... 24
A Formatting Note............................................................................................................ 25
Acknowledgements .......................................................................................................... 26
Free Ebooks from Microsoft Press ..................................................................................... 28
The “Microsoft Press Guided Tours” App ........................................................................... 28
Errata & Book Support ...................................................................................................... 28
We Want to Hear from You............................................................................................... 29
Stay in Touch ................................................................................................................... 29
Chapter 1 The Life Story of a Windows Store App: Characteristics of the
Windows Platform .............................................................................................................. 30
Leaving Home: Onboarding to the Windows Store ............................................................. 32
Discovery, Acquisition, and Installation.............................................................................. 35
Playing in Your Own Room: The App Container .................................................................. 39
Different Views of Life: Views and Resolution Scaling ......................................................... 42
Those Capabilities Again: Getting to Data and Devices ........................................................ 46
Taking a Break, Getting Some Rest: Process Lifecycle Management ..................................... 49
Remembering Yourself: App State and Roaming................................................................. 51
Coming Back Home: Updates and New Opportunities ........................................................ 56
And, Oh Yes, Then There’s Design ..................................................................................... 58
Feature Roadmap and Cross-Reference ............................................................................. 59
Chapter 2 Quickstart .......................................................................................................... 65
A Really Quick Quickstart: The Blank App Template ............................................................ 65
Blank App Project Structure .......................................................................................... 68

2
 QuickStart #1: Here My Am! and an Introduction to Blend for Visual Studio ........................ 72
Design Wireframes ....................................................................................................... 73
Create the Markup ....................................................................................................... 76
Styling in Blend............................................................................................................. 78
Adding the Code........................................................................................................... 83
Extra Credit: Improving the App ........................................................................................ 97
Receiving Messages from the iframe ............................................................................. 98
Improving the Placeholder Image with a Canvas Element ................................................ 99
Handling Variable Image Sizes ..................................................................................... 100
Moving the Captured Image to AppData (or the Pictures Library) .................................. 103
Using a Thumbnail Instead of the Full Image ................................................................ 105
The Other Templates: Projects and Items ........................................................................ 107
Navigation App Template............................................................................................ 107
Grid App Template ..................................................................................................... 107
Hub App Template...................................................................................................... 108
Split Template ............................................................................................................ 108
Item Templates .......................................................................................................... 108
What We’ve Just Learned ............................................................................................... 109
Chapter 3 App Anatomy and Performance Fundamentals .................................................. 111
App Activation ............................................................................................................... 112
Branding Your App 101: The Splash Screen and Other Visuals ....................................... 113
Activation Event Sequence .......................................................................................... 117
Activation Code Paths ................................................................................................. 119
WinJS.Application Events ............................................................................................ 121
Optimizing Startup Time ............................................................................................. 124
WinRT Events and removeEventListener.......................................................................... 126
App Lifecycle Transition Events and Session State ............................................................ 128
Suspend, Resume, and Terminate................................................................................ 129

3
 Basic Session State in Here My Am! ............................................................................. 133
Page Controls and Navigation ......................................................................................... 136
WinJS Tools for Pages and Page Navigation .................................................................. 136
The Navigation App Template, PageControl Structure, and PageControlNavigator ......... 139
The Navigation Process and Navigation Styles .............................................................. 146
Optimizing Page Switching: Show-and-Hide ................................................................. 148
Page-Specific Styling ................................................................................................... 149
Async Operations: Be True to Your Promises .................................................................... 151
Using Promises ........................................................................................................... 151
Joining Parallel Promises ............................................................................................. 153
Sequential Promises: Nesting and Chaining .................................................................. 153
Managing the UI Thread with the WinJS Scheduler........................................................... 156
Scheduler Priorities .................................................................................................... 157
Scheduling and Managing Tasks .................................................................................. 158
Setting Priority in Promise Chains ................................................................................ 160
Long-Running Tasks .................................................................................................... 162
Debugging and Profiling.................................................................................................. 165
Debug Output and Logging.......................................................................................... 165
Error Reports and the Event Viewer............................................................................. 166
Async Debugging ........................................................................................................ 169
Performance and Memory Analysis ............................................................................. 170
The Windows App Certification Toolkit ........................................................................ 175
What We’ve Just Learned ............................................................................................... 176
Chapter 4 Web Content and Services ................................................................................ 177
Network Information and Connectivity ............................................................................ 179
Network Types in the Manifest.................................................................................... 180
Network Information (the Network Object Roster) ....................................................... 181
The ConnectionProfile Object...................................................................................... 183

4
 Connectivity Events .................................................................................................... 184
Cost Awareness .......................................................................................................... 185
Running Offline .......................................................................................................... 189
Hosting Content: the WebView and iframe Elements ....................................................... 191
Local and Web Contexts (and iframe Elements) ............................................................ 192
Dynamic Content........................................................................................................ 195
App Content URIs ....................................................................................................... 197
The <x-ms-webview> Element..................................................................................... 198
HTTP Requests ............................................................................................................... 209
Using WinJS.xhr.......................................................................................................... 210
Using Windows.Web.Http.HttpClient........................................................................... 211
Suspend and Resume with Online Content................................................................... 216
Prefetching Content ................................................................................................... 218
Background Transfer ...................................................................................................... 219
Basic Downloads ........................................................................................................ 221
Basic Uploads ............................................................................................................. 225
Completion and Error Notifications ............................................................................. 226
Providing Headers and Credentials .............................................................................. 227
Setting Cost Policy ...................................................................................................... 227
Grouping Transfers ..................................................................................................... 228
Suspend, Resume, and Restart with Background Transfers ............................................ 228
Authentication, the Microsoft Account, and the User Profile ............................................ 230
The Credential Locker ................................................................................................. 231
The Web Authentication Broker .................................................................................. 233
Single Sign-On ............................................................................................................ 237
Using the Microsoft Account ....................................................................................... 238
The User Profile (and the Lock Screen Image) ............................................................... 244
What We’ve Just Learned ............................................................................................... 246

5
Chapter 5 Controls and Control Styling .............................................................................. 248
The Control Model for HTML, CSS, and JavaScript ............................................................ 249
HTML Controls ............................................................................................................... 251
Extensions to HTML Elements ..................................................................................... 254
WinJS Controls ............................................................................................................... 255
Syntax for data-win-options ........................................................................................ 259
WinJS Control Instantiation ......................................................................................... 261
Strict Processing and processAll Functions ................................................................... 262
Example: WinJS.UI.HtmlControl................................................................................... 263
Example: WinJS.UI.Rating (and Other Simple Controls) ................................................. 264
Example: WinJS.UI.Tooltip .......................................................................................... 265
Example: WinJS.UI.ItemContainer ............................................................................... 266
Working with Controls in Blend ....................................................................................... 269
Control Styling ............................................................................................................... 272
Styling Gallery: HTML Controls .................................................................................... 274
Styling Gallery: WinJS Controls .................................................................................... 276
Some Tips and Tricks .................................................................................................. 284
Custom Controls ............................................................................................................ 285
Implementing the Dispose Pattern .............................................................................. 288
Custom Control Examples ........................................................................................... 289
Custom Controls in Blend ............................................................................................ 293
What We’ve Just Learned ............................................................................................... 297
Chapter 6 Data Binding, Templates, and Collections .......................................................... 298
Data Binding .................................................................................................................. 299
Data Binding Basics..................................................................................................... 299
Data Binding in WinJS ................................................................................................. 301
Under the Covers: Binding mixins ................................................................................ 311
Programmatic Binding and WinJS.Binding.bind............................................................. 313

6
 Binding Initializers ...................................................................................................... 315
Binding Templates.......................................................................................................... 319
Template Options, Properties, and Compilation ........................................................... 322
Collection Data Types ..................................................................................................... 324
Windows.Foundation.Collection Types ........................................................................ 325
WinJS Binding Lists ..................................................................................................... 331
What We’ve Just Learned ............................................................................................... 342
Chapter 7 Collection Controls ........................................................................................... 344
Collection Control Basics................................................................................................. 345
Quickstart #1: The WinJS Repeater Control with HTML controls .................................... 345
Quickstart #2: The FlipView Control Sample ................................................................. 349
Quickstart #3: The ListView Essentials Sample .............................................................. 351
Quickstart #4: The ListView Grouping Sample .............................................................. 353
ListView in the Grid App Project Template ................................................................... 357
The Semantic Zoom Control ............................................................................................ 361
How Templates Work with Collection Controls................................................................. 364
Referring to Templates ............................................................................................... 364
Template Functions (Part 1): The Basics ....................................................................... 365
Creating Templates from Data Sources in Blend ........................................................... 368
Repeater Features and Styling......................................................................................... 372
FlipView Features and Styling.......................................................................................... 377
Collection Control Data Sources ...................................................................................... 380
The Structure of Data Sources (Interfaces Aplenty!)...................................................... 381
A FlipView Using the Pictures Library ........................................................................... 384
Custom Data Sources and WinJS.UI.VirtualizedDataSource ........................................... 386
ListView Features and Styling .......................................................................................... 393
When Is ListView the Right Choice? ............................................................................. 393
Options, Selections, and Item Methods........................................................................ 395

7
 Styling ....................................................................................................................... 399
Loading State Transitions ............................................................................................ 401
Drag and Drop ............................................................................................................ 402
Layouts ...................................................................................................................... 405
Template Functions (Part 2): Optimizing Item Rendering .................................................. 414
What We’ve Just Learned ............................................................................................... 419
Chapter 8 Layout and Views ............................................................................................. 421
Principles of Page Layout ................................................................................................ 423
Sizing, Scaling, and Views: The Many Faces of Your App.................................................... 426
Variable View Sizing and Orientations .......................................................................... 426
Screen Resolution, Pixel Density, and Scaling ............................................................... 437
Multiple Views ........................................................................................................... 442
Pannable Sections and Styles .......................................................................................... 446
Laying Out the Hub ..................................................................................................... 447
Laying Out the Sections .............................................................................................. 448
Panning Styles and Railing ........................................................................................... 449
Panning Snap Points and Limits ................................................................................... 451
Zooming Snap Points and Limits .................................................................................. 452
The Hub Control and Hub App Template.......................................................................... 453
Hub Control Styling..................................................................................................... 460
Using the CSS Grid .......................................................................................................... 461
Overflowing a Grid Cell ............................................................................................... 463
Centering Content Vertically ....................................................................................... 463
Scaling Font Size ......................................................................................................... 464
Item Layout ................................................................................................................... 465
CSS 2D and 3D Transforms .......................................................................................... 466
Flexbox ...................................................................................................................... 466
Nested and Inline Grids............................................................................................... 467

8
 Fonts and Text Overflow ............................................................................................. 468
Multicolumn Elements and Regions ............................................................................. 470
What We’ve Just Learned ............................................................................................... 472
Chapter 9 Commanding UI ................................................................................................ 474
Where to Place Commands ............................................................................................. 475
The App Bar and Nav Bar ................................................................................................ 480
App Bar Basics and Standard Commands ..................................................................... 481
App Bar Styling ........................................................................................................... 490
Command Menus ....................................................................................................... 494
Custom App Bars ........................................................................................................ 495
Nav Bar Features ........................................................................................................ 497
Nav Bar Styling ........................................................................................................... 505
Flyouts and Menus ......................................................................................................... 507
WinJS.UI.Flyout Properties, Methods, and Events......................................................... 509
Flyout Examples ......................................................................................................... 510
Menus and Menu Commands ..................................................................................... 513
Message Dialogs ............................................................................................................ 518
Improving Error Handling in Here My Am! ....................................................................... 519
What We’ve Just Learned ............................................................................................... 525
Chapter 10 The Story of State, Part 1: App Data and Settings ............................................. 527
The Story of State........................................................................................................... 529
App Data Locations..................................................................................................... 532
App Data APIs (WinRT and WinJS) ................................................................................... 533
Settings Containers..................................................................................................... 534
State Versioning ......................................................................................................... 536
Folders, Files, and Streams.............................................................................................. 537
FileIO, PathIO, and WinJS Helpers (plus FileReader) ...................................................... 543
Encryption and Compression....................................................................................... 544

9
 Q&A on Files, Streams, Buffers, and Blobs.................................................................... 544
Using App Data APIs for State Management..................................................................... 552
Transient Session State ............................................................................................... 552
Local and Temporary State.......................................................................................... 553
IndexedDB, SQLite, and Other Database Options .......................................................... 555
Roaming State ............................................................................................................ 556
Settings Pane and UI....................................................................................................... 559
Design Guidelines for Settings ..................................................................................... 561
Populating Commands ................................................................................................ 563
Implementing Commands: Links and Settings Flyouts ................................................... 566
Programmatically Invoking Settings Flyouts.................................................................. 568
Here My Am! Update ..................................................................................................... 570
What We’ve Just Learned ............................................................................................... 571
Chapter 11 The Story of State, Part 2: User Data, Files, and OneDrive ................................ 573
The Big Picture of User Data ........................................................................................... 574
Using the File Picker and Access Cache ............................................................................ 579
The File Picker UI ........................................................................................................ 580
The File Picker API ...................................................................................................... 585
Access Cache.............................................................................................................. 589
StorageFile Properties and Metadata .............................................................................. 592
Availability ................................................................................................................. 593
Thumbnails ................................................................................................................ 594
File Properties ............................................................................................................ 598
Media-Specific Properties ........................................................................................... 601
Folders and Folder Queries ............................................................................................. 607
KnownFolders and the StorageLibrary Object ............................................................... 609
Removable Storage .................................................................................................... 612
Simple Enumeration and Common Queries .................................................................. 613

10
 Custom Queries.......................................................................................................... 618
Metadata Prefetching with Queries ............................................................................. 623
Creating Gallery Experiences........................................................................................... 625
File Activation and Association ........................................................................................ 627
What We’ve Just Learned ............................................................................................... 632
Chapter 12 Input and Sensors ........................................................................................... 634
Touch, Mouse, and Stylus Input ...................................................................................... 635
The Touch Language and Mouse/Keyboard Equivalents ................................................ 636
What Input Capabilities Are Present? .......................................................................... 643
Unified Pointer Events ................................................................................................ 645
Gesture Events ........................................................................................................... 649
The Gesture Recognizer .............................................................................................. 658
Keyboard Input and the Soft Keyboard ............................................................................ 659
Soft Keyboard Appearance and Configuration .............................................................. 660
Adjusting Layout for the Soft Keyboard ........................................................................ 663
Standard Keystrokes ................................................................................................... 666
Inking ............................................................................................................................ 667
Geolocation ................................................................................................................... 669
Geofencing ................................................................................................................ 673
Sensors.......................................................................................................................... 676
What We’ve Just Learned ............................................................................................... 680
Chapter 13 Media............................................................................................................. 681
Creating Media Elements ................................................................................................ 682
Graphics Elements: Img, Svg, and Canvas (and a Little CSS) ............................................... 684
Additional Characteristics of Graphics Elements ........................................................... 688
Some Tips and Tricks .................................................................................................. 689
Rendering PDFs .......................................................................................................... 694
Video Playback and Deferred Loading.............................................................................. 699

11
 Disabling Screen Savers and the Lock Screen During Playback ....................................... 703
Video Element Extension APIs ..................................................................................... 703
Applying a Video Effect ............................................................................................... 705
Browsing Media Servers.............................................................................................. 706
Audio Playback and Mixing ............................................................................................. 706
Audio Element Extension APIs ..................................................................................... 708
Playback Manager and Background Audio .................................................................... 708
The Media Transport Control UI .................................................................................. 714
Playing Sequential Audio ............................................................................................. 717
Playlists ......................................................................................................................... 719
Text to Speech ............................................................................................................... 723
Loading and Manipulating Media .................................................................................... 725
Image Manipulation and Encoding............................................................................... 726
Manipulating Audio and Video .................................................................................... 732
Handling Custom Audio and Video Formats ................................................................. 735
Media Capture ............................................................................................................... 742
Flexible Capture with the MediaCapture Object ........................................................... 744
Selecting a Media Capture Device................................................................................ 748
Streaming Media and Play To .......................................................................................... 751
Streaming from a Server and Digital Rights Management.............................................. 751
Streaming from App to Network.................................................................................. 753
Play To ....................................................................................................................... 754
What We Have Learned .................................................................................................. 757
Chapter 14 Purposeful Animations.................................................................................... 759
Systemwide Enabling and Disabling of Animatio ns ........................................................... 761
The WinJS Animations Library ......................................................................................... 762
Animations in Action .................................................................................................. 765
CSS Animations and Transitions ...................................................................................... 769

12
 Designing Animations in Blend for Visual Studio ........................................................... 775
The HTML Independent Animations Sample ................................................................. 777
Rolling Your Own: Tips and Tricks .................................................................................... 779
What We’ve Just Learned ............................................................................................... 785
Chapter 15 Contracts ........................................................................................................ 786
Share ............................................................................................................................. 788
Share Source Apps...................................................................................................... 793
Share Target Apps ...................................................................................................... 805
The Clipboard............................................................................................................. 816
Launching Apps with URI Scheme Associations ................................................................ 818
Search ........................................................................................................................... 823
The Search Charm UI .................................................................................................. 825
The WinJS.UI.SearchBox Control.................................................................................. 829
Providing Query Suggestions ....................................................................................... 831
Providing Result Suggestions ....................................................................................... 835
SearchBox Styling ....................................................................................................... 837
Indexing and Searching Content .................................................................................. 840
The Search Contract ................................................................................................... 849
Contacts ........................................................................................................................ 850
Contact Cards............................................................................................................. 850
Using the Contact Picker ............................................................................................. 856
Appointments ................................................................................................................ 860
What We’ve Just Learned ............................................................................................... 864
Chapter 16 Alive with Activity: Tiles, Notifications, the Lock Screen, and
Background Tasks.............................................................................................................. 865
Alive with Activity: A Visual Tour ..................................................................................... 866
The Four Sources of Updates and Notifications ................................................................ 875
Tiles, Secondary Tiles, and Badges ................................................................................... 878

13
 Secondary Tiles .......................................................................................................... 880
Basic Tile Updates ...................................................................................................... 887
Cycling, Scheduled, and Expiring Updates .................................................................... 900
Badge Updates ........................................................................................................... 902
Periodic Updates ............................................................................................................ 904
Creating an Update Service ......................................................................................... 907
Debugging a Service Using the Localhost...................................................................... 911
Windows Azure and Azure Mobile Services .................................................................. 912
Toast Notifications ......................................................................................................... 917
Creating Basic Toasts .................................................................................................. 919
Butter and Jam: Options for Your Toast ....................................................................... 921
Tea Time: Scheduled Toasts and Alarms....................................................................... 923
Toast Events and Activation ........................................................................................ 926
Push Notifications and the Windows Push Notification Service ......................................... 927
Requesting and Caching a Channel URI (App) ............................................................... 929
Managing Channel URIs (Service) ................................................................................ 931
Sending Updates and Notifications (Service) ................................................................ 932
Raw Notifications (Service).......................................................................................... 933
Receiving Notifications (App) ...................................................................................... 934
Debugging Tips ........................................................................................................... 935
Tools and Providers for Push Notifications ................................................................... 935
Background Tasks and Lock Screen Apps.......................................................................... 937
Background Tasks in the Manifest ............................................................................... 938
Building and Registering Background Tasks .................................................................. 939
Conditions ................................................................................................................. 941
Tasks for Maintenance Triggers ................................................................................... 942
Tasks for System Triggers (Non-Lock Screen) ................................................................ 944
Lock Screen–Dependent Tasks and Triggers ................................................................. 945

14
 Debugging Background Tasks ...................................................................................... 949
What We’ve Just Learned (Whew!) ................................................................................. 950
Chapter 17 Devices and Printing ....................................................................................... 952
Declaring Device Access.................................................................................................. 956
Enumerating and Watching Devices ................................................................................ 957
Scenario API Devices ...................................................................................................... 962
Image Scanners .......................................................................................................... 962
Barcode and Magnetic Stripe Readers (Point-of-Service Devices) .................................. 967
Smartcards................................................................................................................. 970
Fingerprint (Biometric) Readers................................................................................... 971
Bluetooth Call Control ................................................................................................ 972
Printing Made Easy......................................................................................................... 973
The Printing User Experience ...................................................................................... 974
Print Document Sources ............................................................................................. 977
Providing Print Content and Configuring Options.......................................................... 979
Protocol APIs: HID, USB, Bluetooth, and Wi-Fi Direct ........................................................ 981
Human Interface Devices (HID).................................................................................... 983
Custom USB Devices ................................................................................................... 990
Bluetooth (RFCOMM) ................................................................................................. 992
Bluetooth Smart (LE/GATT) ......................................................................................... 996
Wi-Fi Direct ................................................................................................................ 999
Near Field Communication and the Proximity API............................................................1000
Finding Your Peers (No Pressure!) ..............................................................................1002
Sending One-Shot Payloads: Tap to Share ...................................................................1007
What We’ve Just Learned ..............................................................................................1009
Chapter 18 WinRT Components: An Introduction .............................................................1010
Choosing a Mixed Language Approach (and Web Workers)..............................................1012
Quickstarts: Creating and Debugging Components ..........................................................1014

15
 Quickstart #1: Creating a Component in C# .................................................................1015
Simultaneously Debugging Script and Managed/Native Code .......................................1020
Quickstart #2: Creating a Component in C++ ...............................................................1021
Comparing the Results ...............................................................................................1023
Key Concepts for WinRT Components.............................................................................1026
Implementing Asynchronous Methods .......................................................................1028
Projections into JavaScript .........................................................................................1042
Scenarios for WinRT Components ..................................................................................1044
Higher Performance (Perhaps) ...................................................................................1044
Access to Additional APIs ...........................................................................................1047
Obfuscating Code and Protecting Intellectual Property ................................................1051
Concurrency..............................................................................................................1052
Library Components ..................................................................................................1053
What We’ve Just Learned ..............................................................................................1056
Chapter 19 Apps for Everyone, Part 1: Accessibility and World-Readiness .........................1058
Accessibility ..................................................................................................................1059
Screen Readers and Aria Attributes ............................................................................1063
Handling Contrast Variations ......................................................................................1068
World Readiness and Localization ..................................................................................1075
Globalization .............................................................................................................1077
Preparing for Localization ..........................................................................................1087
Creating Localized Resources: The Multilingual App Toolkit ..........................................1101
Localization Wrap-Up ................................................................................................1108
What We’ve Just Learned ..............................................................................................1109
Chapter 20 Apps for Everyone, Part 2: The Windows Store .............................................1110
Your App, Your Business ................................................................................................1111
Planning: Can the App Be a Windows Store App? ........................................................1113
Planning for Monetization (or Not) .............................................................................1114

16
 Growing Your Customer Base and Other Value Exchanges ...........................................1125
Measuring and Experimenting with Revenue Performance ..........................................1126
The Windows Store APIs ................................................................................................1127
The CurrentAppSimulator Object................................................................................1130
Trial Versions and App Purchase.................................................................................1133
Listing and Purchasing In-App Products.......................................................................1137
Handling Large Catalogs .............................................................................................1145
Receipts ....................................................................................................................1146
Instrumenting Your App for Telemetry and Analytics .......................................................1148
Releasing Your App to the World....................................................................................1155
Promotional Screenshots, Store Graphics, and Text Copy.............................................1156
Testing and Pre-Certification Tools .............................................................................1158
Creating the App Package ..........................................................................................1159
Onboarding and Working through Rejection ...............................................................1163
App Updates .................................................................................................................1166
Getting Known: Marketing, Discoverability, and the Web ................................................1168
Connecting Your Website and Web-Mapped Search Results ........................................1170
Face It: You’re Running a Business! ................................................................................1171
Look for Opportunities...............................................................................................1172
Invest in Your Business ..............................................................................................1172
Fear Not the Marketing .............................................................................................1172
Support Your Customers ............................................................................................1173
Plan for the Future ....................................................................................................1173
Selling Your App When It’s Not Running......................................................................1174
You’re Not Alone .......................................................................................................1175
Final Thoughts: Qualities of a Rock Star App ...................................................................1175
What We’ve Just Learned ..............................................................................................1176
Appendix A Demystifying Promises..................................................................................1178

17
 What Is a Promise, Exactly? The Promise Relationships ...................................................1178
The Promise Construct (Core Relationship) .....................................................................1181
Example #1: An Empty Promise! .................................................................................1183
Example #2: An Empty Async Promise.........................................................................1185
Example #3: Retrieving Data from a URI ......................................................................1186
Benefits of Promises ......................................................................................................1187
The Full Promise Construct ............................................................................................1188
Nesting Promises.......................................................................................................1192
Chaining Promises .....................................................................................................1195
Promises in WinJS (Thank You, Microsoft!) .....................................................................1200
The WinJS.Promise Class ............................................................................................1201
Originating Errors with WinJS.Promise.WrapError .......................................................1203
Some Interesting Promise Code .....................................................................................1204
Delivering a Value in the Future: WinJS.Promise.timeout .............................................1204
Internals of WinJS.Promise.timeout ............................................................................1205
Parallel Requests to a List of URIs ...............................................................................1205
Parallel Promises with Sequential Results ...................................................................1206
Constructing a Sequential Promise Chain from an Array...............................................1208
PageControlNavigator._navigating (Page Control Rendering) .......................................1208
Bonus: Deconstructing the ListView Batching Renderer ...................................................1210
Appendix B WinJS Extras .................................................................................................1214
Exploring WinJS.Class Patterns .......................................................................................1214
WinJS.Class.define .....................................................................................................1214
WinJS.Class.derive .....................................................................................................1217
Mixins.......................................................................................................................1218
Obscure WinJS Features ................................................................................................1219
Wrappers for Common DOM Operations ....................................................................1219
WinJS.Utilities.data, convertToPixels, and Other Positional Methods ............................1221

18
 WinJS.Utilities.empty, eventWithinElement, and getMember ......................................1222
WinJS.UI.scopedSelect and getItemsFromRanges ........................................................1222
Extended Splash Screens ...............................................................................................1223
Adjustments for View Sizes ........................................................................................1229
Custom Layouts for the ListView Control ........................................................................1231
Minimal Vertical Layout .............................................................................................1233
Minimal Horizontal Layout .........................................................................................1235
Two-Dimensional and Nonlinear Layouts ....................................................................1239
Virtualization ............................................................................................................1241
Grouping...................................................................................................................1243
The Other Stuff .........................................................................................................1244
Appendix C Additional Networking Topics........................................................................1249
XMLHttpRequest and WinJS.xhr .....................................................................................1249
Tips and Tricks for WinJS.xhr ......................................................................................1250
Breaking Up Large Files (Background Transfer API) ..........................................................1251
Multipart Uploads (Background Transfer API) .................................................................1252
Notes on Encryption, Decryption, Data Protection, and Certificates .................................1255
Syndication: RSS, AtomPub, and XML APIs in WinRT ........................................................1255
Reading RSS Feeds .....................................................................................................1256
Using AtomPub .........................................................................................................1259
Sockets .........................................................................................................................1260
Datagram Sockets......................................................................................................1261
Stream Sockets..........................................................................................................1265
Web Sockets: MessageWebSocket and StreamWebSocket...........................................1268
The ControlChannelTrigger Background Task ..............................................................1273
The Credential Picker UI ................................................................................................1273
Other Networking SDK Samples .....................................................................................1277
Appendix D Provider-Side Contracts ................................................................................1279

19
 File Picker Providers ......................................................................................................1279
Manifest Declarations................................................................................................1280
Activation of a File Picker Provider..............................................................................1281
Cached File Updater ......................................................................................................1288
Updating a Local File: UI.............................................................................................1291
Updating a Remote File: UI ........................................................................................1292
Update Events ...........................................................................................................1294
Contact Cards Action Providers ......................................................................................1297
Contact Picker Providers ................................................................................................1300
Appointment Providers..................................................................................................1303
About the Author .............................................................................................................1309

20
Introduction
Welcome, my friends, to Windows 8.1! On behalf of the thousands of designers, program managers,
developers, test engineers, and writers who have brought the product to life, I'm del ighted to welcome
you into a world of Windows Reimagined.

This theme is no mere sentimental marketing ploy, intended to bestow an aura of newness to
something that is essentially unchanged, like those household products that make a big splash on the
idea of "New and Improved Packaging!" No, starting with version 8, Microsoft Windows truly has been
reborn—after more than a quarter-century, something genuinely new has emerged.

I suspect—indeed expect—that you're already somewhat familiar with the reimagined user
experience of Windows 8 and Windows 8.1. You're probably reading this book, in fact, because you
know that the ability of Windows to reach across desktop, laptop, and tablet devices, along with the
global reach of the Windows Store, will provide you with many business opportunities, whether you're
in business, as I like to say, for fame, fortune, fun, or philanthropy.

We'll certainly see many facets of this new user experience throughout the course of this book. Our
primary focus, however, will be on the reimagined developer experience.

I don't say this lightly. When I first began giving presentations within Microsoft about building
Windows Store apps, I liked to show a slide of what the world was like in the year 1985. It was the time
of Ronald Reagan, Margaret Thatcher, and Cold War tensions. It was the time of VCRs and the
discovery of AIDS. It was when Back to the Future was first released, Michael Jackson topped the charts
with Thriller, and Steve Jobs was kicked out of Apple. And it was when software developers got their
first taste of the original Windows API and the programming model for desktop applications.

The longevity of that programming model has been impressive. It's been in place for nearly three
decades now and has grown to become the heart of the largest business ecosystem on the planet. The
API itself, known today as Win32, has also grown to become the largest on the planet! What started
out on the order of about 300 callable methods has expanded three orders of magnitude, well beyond
the point that any one individual could even hope to understand a fraction of it. I'd certainly given up
such futile efforts myself.

So when I bumped into my old friend Kyle Marsh in the fall of 2009, just after Windows 7 had been
released, and heard from him that Microsoft was planning to reinvigorate native app development for
Windows 8, my ears were keen to listen. In the months that followed I learned that Microsoft was
introducing a completely new API called the Windows Runtime (or WinRT). This wasn't mea nt to
replace Win32, mind you; desktop applications would still be supported. No, this was a programming
model built from the ground up for a new breed of touch-centric, immersive apps that could compete
with those emerging on various mobile platforms. It would be designed from the app developer's point
of view, rather than the system's, so that key features would take only a few lines of code to implement

21
rather than hundreds or thousands. It would also enable direct native app development in multiple
programming languages. This meant that new operating system capabilities would surface to those
developers without having to wait for an update to some intermediate framework. It also meant that
developers who had experience in any one of those language choices would find a natural home when
writing apps for Windows 8 and Windows 8.1.

This was very exciting news to me because the last time that Microsoft did anything significant to
the Windows programming model was in the early 1990s with a technology called the Component
Object Model (COM), which is exactly what allowed the Win32 API to explode as it did. Ironically, it was
my role at that time to introduce COM to the developer community, which I did through two editions
of Inside OLE (Microsoft Press, 1993 and 1995) and seemingly endless travel to speak at conferences
and visit partner companies. History, indeed, does tend to repeat itself, for here I am again, with
another second edition!

In December 2010, I was part of the small team who set out to write the very first Windows Store
apps using what parts of the new WinRT API had become available. Notepad was the text editor of
choice, we built and ran apps on the command line by using abstruse Powershell scripts that required
us to manually type out ungodly hash strings, we had no documentation other than oft-incomplete
functional specifications, and we basically had no debugger to speak of other than the tried and true
window.alert and document.writeln. Indeed, we generally worked out as much HTML, CSS, and
JavaScript as we could inside a browser with F12 debugging tools, adding WinRT-specific code only at
the end because browsers couldn't resolve those APIs. You can imagine how we celebrated when we
got anything to work at all!

Fortunately, it wasn't long before tools like Visual Studio Express and Blend for Visual Studio became
available. By the spring of 2011, when I was giving many training sessions to people inside Microsoft on
building apps for Windows 8, the process was becoming far more enjoyable and exc eedingly more
productive. Indeed, while it took us four to six weeks in late 2010 to get even Hello World to show up
on the screen, by the fall of 2011 we were working with partner companies who pulled together
complete Store-ready apps in roughly the same amount of time.

As we've seen—thankfully fulfilling our expectations—it's possible to build a great app in a matter
of weeks. I'm hoping that this ebook, along with the extensive resources on http://dev.windows.com,
will help you to accomplish exactly that and to reimagine your own designs.

Work on this second edition began almost as soon as the first edition was released. (I’d make a quip
about the ink not being dry, but that analogy doesn’t work for an ebook!) When Windows 8 became
generally available in the fall of 2012, work on Windows 8.1 was already well underway: the
engineering team had a long list of improvements they wanted to make along with features that they
weren’t able to complete for Windows 8. And in the very short span of one year, Windows 8.1 was itself
ready to ship.

At first I thought writing this second edition would be primarily a matter of making small updates to
each chapter and perhaps adding some pages here and there on a handful of new features. But as I got
deeper into the updated platform, I was amazed at just how much the API surface area had expanded!
22
 Windows 8.1 introduces a number of additional controls, an HTML webview element, a stronger HTTP
API, content indexing, deeper OneDrive support, better media capabilities, more tiles sizes (small and
large), more flexible secondary tile, access to many kinds of peripheral devices, and more options for
working with the Windows Store, like consumable in-app purchases. And clearly, this is a very short list
of distinct Windows 8.1 features that doesn’t include the many smaller changes to the API. (A fuller list
can be found on Windows 8.1: New APIs and features for developers).

Furthermore, even as I was wrapping up the first edition of this book, I already had a long list of
topics I wanted to explore in more depth. I wrote a number of those pieces for my blog, with the
intention of including them in this second edition. A prime example is Appendix A, “Demystifying
Promises.”

All in all, then, what was already a very comprehensive book in the first edition has become even
more so in the second! Fortunately, with this being an ebook, neither you nor I need feel guilty about
matters of deforestation. We can simply enjoy the process of learning about and writing Windows
Store Apps with HTML, CSS, and JavaScript.

And what about Windows Phone 8.1? I’m glad you asked, because much of this book is completely
applicable to that platform. Yes, that’s right: Windows Phone 8.1 supports writing apps in HTML, CSS,
and JavaScript, just like Windows 8.1, meaning that you have the same flexibility of implementation
languages on both. However, the decision to support JavaScript apps on Windows Phone 8.1 came very
late in the production of this book, so I’m only able to make a few notes here and there for Phone -
specific concerns. I encourage you to follow the Building Apps for Windows blog, where we’ll be
posting more about the increasingly unified experience of Windows and Windows Phone.

Who This Book Is For

This book is about writing Windows Store apps using HTML, CSS, and JavaScript. Our primary focus will
be on applying these web technologies within the Windows platform, where there are unique
considerations, and not on exploring the details of those web technologies themselves. For the most
part, I'm assuming that you're already at least somewhat conversant with these standards. We will cover
some of the more salient areas like the CSS grid, which is central to app layout, but otherwise I trust
that you're capable of finding appropriate references for most everything else. For Java Script
specifically, I can recommend Rey Bango’s Required JavaScript Reading list, though I hope you’ll spend
more time reading this book than others!

I'm also assuming that your interest in Windows has at least two basic motivations. One, you
probably want to come up to speed as quickly as you can, perhaps to carve out a foothold in the
Windows Store sooner rather than later. Toward that end, Chapter 2, “Quickstart,” gives you an
immediate experience with the tools, APIs, and some core aspects of app development and the
platform. On the other hand, you probably also want to make the best app you can, one that performs
really well and that takes advantage of the full extent of the platform. Toward this end, I've also

23
 endeavored to make this book comprehensive, helping you at least be aware of what's possible and
where optimizations can be made.

Let me make it clear, though, that my focus in this book is the Windows pla tform. I won’t talk much
about third-party libraries, architectural considerations for app design, and development strategies and
best practices. Some of these will come up from time to time, but mostly in passing.

Nevertheless, many insights have come from working directly with real-world developers on their
real-world apps. As part of the Windows Ecosystem team, myself and my teammates have been on the
front lines bringing those first apps to the Windows Store. This has involved writing bits of code for
those apps and investigating bugs, along with conducting design, code, and performance reviews with
members of the Windows engineering team. As such, one of my goals with this book is to make that
deep understanding available to many more developers, including you!

What You'll Need (Can You Say “Samples”?)

To work through this book, you should have Windows 8.1 (or a later update) installed on your
development machine, along with the Windows SDK and tools. All the tools, along with a number of
other resources, are listed on Developer Downloads for Windows Store Apps. You’ll specifically need
Microsoft Visual Studio Express 2013 for Windows. (Note that for all the screenshots in this book, I
switched Visual Studio from its default “dark” color theme to the “light” theme, as the latter works
better against a white page.)

We’ll also acquire other tools along the way as we need them in this ebook, specifically to run some
of the examples in the companion content. Here’s the short list:

 Live SDK (for Chapter 4)

 Bing Maps SDK for Windows Store Apps (for Chapters 10 and beyond)

 Visual Studio Express 2013 for Web (for Chapter 16)

 Multilingual App Toolkit (for Chapter 19)

Also be sure to visit the Windows 8.1 Samples Pack page and download at least the JavaScript
samples. We'll be drawing from many—if not most—of these samples in the chapters ahead, pulling in
bits of their source code to illustrate how many different tasks are accomplished.

One of my secondary goals in this book, in fact, is to help you understand where and when to use
the tremendous resources in what is clearly the best set of samples I’ve ever seen for any release of
Windows. You’ll often be able to find a piece of code in one of the samples that does exactly what you
need in your app or that is easily modified to suit your purpose. For this reason I’ve made it a point to
personally look through every one of the JavaScript samples, understand what they demonstrate, and
then refer to them in their proper context. This, I hope, will save you the trouble of having to do that
level of research yourself and thus make you more productive in your development efforts.

24
 In some cases I’ve taken one of the SDK samples and made certain modifications, typically to
demonstrate an additional feature but sometimes to fix certain bugs or demonstrate a better
understanding that came about after the sample had to be finalized. I’ve included these modifications
in the companion content for this book, which you can download at

http://aka.ms/BrockschmidtBook2/CompContent

The companion content also contains a few additional examples of my own, which I always refer to
as “examples” to make it clear that they aren’t official SDK content. (I’ve also rebranded the modified
samples to make it clear that they’re part of this book.) I’ve written these examples to fill gaps that the
SDK samples don’t address or to provide a simpler demonstration of a feature that a related sample
shows in a more complex manner. You’ll also find many revisions of an app called “Here My Am!” that
we’ll start building in Chapter 2 and we’ll refine throughout the course of this book. This includes
localizing it into a number of different languages by the time we reach the end.

There are also a number of videos that I’ve made for this book, which more readily show dynamic
effects like animations and user interaction. You can find all of them at

http://aka.ms/BrockschmidtBook2/Videos

Beyond all this, you’ll find that the Windows Store app samples gallery as well as the Visual Studio
sample gallery let you search and browse projects that have been contributed by other developers —
perhaps also you! (On the Visual Studio site, by the way, be sure to filter on Windows Store apps
because the gallery covers all Microsoft platforms.) And of course, there will be many more developers
who share projects on their own.

In this book I occasionally refer to posts on a number of blogs. First are a few older blogs, namely
the Windows 8 App Developer blog, the Windows Store for Developers blog, and—for the Windows 8
backstory of how Microsoft approached this whole process of reimagining the operating system —the
Building Windows 8 blog. As of the release of this book, the two developer blogs have merged into the
Building Apps for Windows blog that I mentioned earlier.

A Formatting Note

Throughout this book, identifiers that appear in code, such as variable names, property names, and API
functions and namespaces, are formatted with a color and a fixed-point font. Here’s an example:
Windows.Storage.ApplicationData.current . At times, certain fully qualified names—those that that
include the entire namespace—can become quite long, so it’s necessary to occasionally hyphenate
them across line breaks, as in Windows.Security.Cryptography.CryptographicBuffer.-
convertStringToBinary. Generally speaking, I’ve tried to hyphenate after a dot or between whole
words but not within a word. In any case, these hyphens are never part of the identifier except in CSS
where hyphens are allowed (as in -ms-high-contrast-adjust) and with HTML attributes like aria-
label or data-win-options.

25
 Occasionally, you’ll also see identifiers that have a different color, as in datarequested. These
specifically point out events that originate from Windows Runtime objects, for which there are a few
special considerations for adding and removing event listeners in JavaScript, as discussed toward the
end of Chapter 3. I make a few reminders about this point throughout the chapters, but the purpose of
this special color is to give you a quick reminder that doesn’t break the flow of the discussion
otherwise.

Acknowledgements

In many ways, this isn't my book—that is, it's not an account of my own experiences and opinions
about writing apps for Windows. I'm serving more as a storyteller, where the story itself has been
written by the thousands of people in the Windows team whose passion and dedication have been a
constant source of inspiration. Writing a book like this wouldn't be possible without all the work that's
gone into customer research; writing specs; implementing, testing, and documenting all the details;
managing daily builds and public releases; and writing again the best set of samples I've ever seen for a
platform. Indeed, the words in some sections come directly from conversations I've had with the people
who designed and developed a particular feature. I'm grateful for their time, and I’m delighted to give
them a voice through which they can share their passion for excellence with you.

A number of individuals deserve special mention for their long-standing support of this project. To
Mahesh Prakriya, Ian LeGrow, Anantha Kancherla, Keith Boyd and their respective teams, with whom
I've worked closely, and to Kathy Carper, Roger Gulrajani, Keith Rowe, Dennis Flanagan, and Adam
Denning, under whom I've had the pleasure of serving.

Thanks also to Devon Musgrave at Microsoft Press, who put in many long hours editing my many
long chapters, many times over. My teammates, Kyle Marsh, Todd Landstad, Shai Hinitz, Patrick
Dengler, Lora Heiny, Leon Braginski, and Joseph Ngari have also been invaluable in sharing what
they've learned in working with real-world partners. A special thanks goes to Kenichiro Tanaka of
Microsoft Japan, for always being the first one to return a reviewed chapter to me and for joyfully
researching different areas of the platform whenever I asked. Many bows to you, my friend! Nods also
to others in our international Windows Ecosystem teams who helped with localizing the Here My Am!
app for Chapter 19: Gilles Peingné, Sam Chang, Celia Pipó Garcia, Juergen Schwertl, Maarten van de
Bospoort, Li-Qun Jia, and Shai Hinitz.

The following individuals all contributed to this book as well, with chapter reviews, answers to my
questions, deep discussions of the details, and much more. I’m grateful to all of you for your time and
support:

Shakil Ahmed Ryan Demopoulos Jakub Kotynia Jason Olson Adam Stritzel

Arvind Aiyar Scott Dickens Jared Krinke Elliot H Omiya Shijun Sun

Jessica Alspaugh Tyler Donahue Victoria Kruse Lisa Ong Ellick Sung

Gaurav Anand Brendan Elliott Nathan Kuchta Larry Osterman Sou Suzuki

26
Chris Anderson Matt Esquivel Elmar Langholz Rohit Pagariya Simon Tao

Erik Anderson David Fields Bonny Lau Ankur Patel Henry Tappen

Axel Andrejs Sean Flynn Wonhee Lee Harry Pierson Chris Tavares

Tarek Ayna Erik Fortune Travis Leithead Steve Proteau David Tepper

Art Baker Jim Galasyn Dale Lemieux Hari Pulapaka Lillian Tseng

Adam Barrus Gavin Gear Chantal Leonard Arun Rabinar Sara Thomas

Megan Bates Derek Gephard Cameron Lerum* Matt Rakow Ryan Thompson

Tyler Beam Marcelo Garcia Gonzalez Brian LeVee Ramu Ramanathan Bill Ticehurst

Matthew Beaver Sean Gilmour Jianfeng Lin Sangeeta Ranjit Peter Torr

Kyle Beck Sunil Gottumukkala Tian Luo Ravi Rao Stephen Toub

Ben Betz Scott Graham Sean Lyndersay Brent Rector Tonu Vanatalu

Johnny Bregar Ben Grover David Machaj Ruben Rios Jeremy Viegas

John Brezak Paul Gusmorino Mike Mastrangelo Dale Rogerson Alwin Vyhmeister

John Bronskill Chris Guzak Jordan Matthiesen Nick Rotondo Nick Waggoner

Jed Brown Zainab Hakim Ian McBurnie David Rousset David Washington

Kathy Carper Rylan Hawkins Sarah McDevitt George Roussos Sarah Waskom

Vincent Celie John Hazen Isaac McGarvey Jake Sabulsky Marc Wautier

Raymond Chen Jerome Holman Jesse McGatha Gus Salloum Josh Williams

Rian Chung Scott Hoogerwerf Matt Merry Michael Sciacqua Lucian Wischik

Arik Cohen Stephen Hufnagel Markus Mielke Perumaal Shanmugam Dave Wood

Justin Cooperman Sean Hume Pavel Minaev Edgar Ruiz Silva Kevin Michael Woley

Michael Crider Mathias Jourdain John Morrow Poorva Singal Charing Wong

Monica Czarny Damian Kedzierski Feras Moussa Karanbir Singh Bernardo Zamora

Nigel D’Souza Suhail Khalid John Mullaly Peter Smith Michael Ziller

Priya Dandawate Deen King-Smith Jan Nelson* Sam Spencer

Darren Davis Daniel Kitchener Marius Niculescu Edward Sproull

Jack Davis Kishore Kotteri Daniel Oliver Ben Srour

* For Jan and Cameron, a special acknowledgement for riding down from Redmond, Washington, to visit me in
Portland, Oregon (where I was living at the time), and sharing an appropriately international Thai lunch while we
discussed localization and multilingual apps.

Let me add that during the production of this second edition, I did manage to lose the extra weight
that I’d gained during the first edition. All things must balance out, I suppose!

Finally, special hugs to my wife Kristi and our son Liam (now seven and a half), who have lovingly

27
 been there the whole time and who don't mind my traipsing through the house to my office either late
at night or early in the morning.

Free Ebooks from Microsoft Press

From technical overviews to drilldowns on special topics, these free ebooks are available in PDF, EPUB,
and/or Mobi for Kindle formats, ready for you to download:

http://aka.ms/mspressfree

The “Microsoft Press Guided Tours” App

Check the Windows Store soon for the Microsoft Press Guided Tours app, which provides insightful
tours of new and evolving technologies created by Microsoft. While you’re exploring each tour’s
original content, the app lets you manipulate and mark that content in ways to make it more useful to
you. You can, of course, do the usual things—such as highlight, add notes, mark as favorite, and mark
to read later—but you can also

 view all links to external documentation and samples in one place via a Resources view;
 sort the Resources view by Favorites, Read Later, and Noted;
 view a list of all your notes and highlights via the app bar;
 share text, code, or links to resources with friends via email; and
 create your own list of resources, as you navigate online resources, beyond those pointed to in the
Guided Tour.

Our first Guided Tour is based on this ebook. Kraig acts as a guide in two senses: he leads
experienced web developers through the processes and best practices for building Windows Store
apps, and he guides you through Microsoft’s extensive developer documentation, pointing you to the
appropriate resources at each step in your app development process so that you can build your apps as
effectively as possible.

Enjoy the app, and we look forward to providing more Guided Tours soon!

Errata & Book Support

We’ve made every effort to ensure the accuracy of this ebook and its companion content. Any errors
that are reported after the book’s publication will be listed on http://aka.ms/BrockschmidtBook2/Errata.
If you find an error that is not already listed, you can report it to us through the comments area of the
same page.

28
Random documents with unrelated
content Scribd suggests to you:
this Bay, where are many Iles, and questionlesse good harbors: and
then the Countrie of the Massachusets, which is the Paradise of all
those parts: for, heere are many Iles all planted with corne; groves,
mulberries, salvage gardens, and good harbors: the Coast is for the
most part, high clayie sandie cliffs. The Sea Coast as you passe,
shewes you all along large corne fields, and great troupes of well
proportioned people: but the French having remained heere neere
sixe weekes, left nothing for us to take occasion to examine the
inhabitants relations, viz. if there be neer three thousand people
upon these Iles; and that the River doth pearce many daies iourneis
the intralles of that Countrey. We found the people in those parts
verie kinde; but in their furie no lesse valiant. For, upon a quarrell
wee had with one of them, hee onely with three others crossed the
harbor of Quonahassit to certaine rocks whereby wee must passe;
and there let flie their arrowes for our shot, till we were out of
danger.
Then come you to Accomack, an excellent good harbor, good land;
and no want of any thing, but industrious people. After much
kindnesse, upon a small occasion, wee fought also with fortie or
fiftie of those: though some were hurt, and some slaine; yet within
an houre after they became friendes. Cape Cod is the next presents
it selfe: which is onely a headland of high hils of sand, Cape Cod
overgrowne with shrubbie pines, hurts, and such
trash; but an excellent harbor for all weathers. This Cape is made by
the maine Sea on the one side, and a great Bay on the other in
forme of a sickle: on it doth inhabit the people of Pawmet: and in
the bottome of the Bay, the people of Chawum. Towards the South
and South west of this Cape, is found a long and dangerous shoale
of sands and rocks. But so farre as I incircled it, I found thirtie
fadom water aboard the shore and a strong current: which makes
mee think there is a Channell about this shoale; where is the best
and greatest fish to be had, Winter and Summer, in all that Countrie.
But, the Salvages say there is no Channell, but that the shoales
beginne from the maine at Pawmet, to the Ile of Nausit; and so
extends beyond their knowledge into the Sea. The next to this is
Capawack, and those abounding Countries of copper, corne, people,
and mineralls; which I went to discover this last yeare: but because I
miscarried by the way, I will leave them, till God please I have better
acquaintance with them.
The Massachusets, they report, sometimes have warres with the
Bashabes of Pennobscot; and are not alwaies friends with them of
Chawum and their alliants: but now they are all friends, and have
each trade with other, so farre as they have societie, on each others
frontiers. For they make no such voiages as from Pennobscot to
Cape Cod; seldom to Massachewset. In the North (as I have said)
they begunne to plant corne, whereof the South part hath such
plentie, as they have what they will from them of the North; and in
the Winter much more plenty of fish and foule: but both Winter and
Summer hath it in the one part or other all the yeare; being the
meane and most indifferent temper, betwixt heat and colde, of all
the regions betwixt the Lyne and the Pole: but the furs Northward
are much better, and in much more plentie, then Southward.
The remarkablest Iles and mountains for Landmarkes are these;
The highest Ile or Sorico, in the Bay of Pennobscot: but the three
Iles and a rock of Matinnack are much furder in the Sea; Metinicus is
also three plaine Iles and a rock, betwixt it and Monahigan:
Monahigan is a rounde high Ile; and close by it Monanis, betwixt
which is a small harbor where we ride. In Damerils Iles is such
another: Sagadahock is knowne by Satquin, and foure or five Iles in
the mouth. Smyths Iles are a heape together, none neere them,
against Accominticus. The three Turks heads are three Iles seen far
to Sea-ward in regard of the head-land.
The cheefe headlands are onely Cape Tragabigzanda and Cape
Cod.
The cheefe mountaines, them of Pennobscot: the twinkling
mountaine of Aucocisco; the greate mountaine of Sasanou; and the
high mountaine of Massachusit: each of which you shall finde in the
Mappe; their places, formes, and altitude. The waters are most pure,
proceeding from the intrals of rockie mountaines; the hearbes and
fruits are of many sorts and kindes: as alkermes, currans, or a fruit
like currans, mulberries, vines, respices, goosberries, plummes,
walnuts, chesnuts, small nuts, &c. pumpions, gourds, strawberries,
beans, pease, and mayze: a kinde or two of flax, wherewith they
make nets, lines and ropes both small and great, verie strong for
their quantities.
Oke, is the chiefe wood; of which there is great difference in
regard of the soyle where it groweth, firre, pyne, walnut, chestnut,
birch, ash, elme, cypresse, ceder, mulberrie, plum-tree, hazell,
saxefrage, and many other sorts.
Eagles, Gripes, diverse sorts of Haukes, Cranes, Geese, Brants,
Cormorants, Ducks, Sheldrakes, Teale, Meawes, Guls, Turkies, Dive-
doppers, and many other sorts, whose names I knowe not.
Whales, Grampus, Porkpisces, Turbot, Sturgion, Cod, Hake,
Haddock, Cole, Cusk, or small Ling, Shark, Mackerrell, Herring,
Mullet, Base, Pinacks, Cunners, Pearch, Eels, Crabs, Lobsters,
Muskles, Wilkes, Oysters, and diverse others &c.
Moos, a beast bigger than a Stagge; Deere, red, and Fallow;
Bevers, Wolves, Foxes, both blacke and other; Aroughconds, Wild-
cats, Beares, Otters, Martins, Fitches, Musquassus, and diverse sorts
of vermine, whose names I know not. All these and divers other
good things do heere, for want of use, still increase, and decrease
with little diminution, whereby they growe to that abundance. You
shall scarce finde any Baye, shallow shore or Cove of sand, where
you may not take many Clampes, or Lobsters, or both at your
pleasure, and in many places lode your boat if you please; Nor Iles
where you finde not fruits, birds, crabs, and muskles, or all of them,
for taking, at a lowe water. And in the harbors we frequented, a little
boye might take of Cunners, and Pinacks, and such delicate fish, at
the ships sterne, more than sixe or tenne can eate in a daie; but
with a casting net, thousands when wee pleased: and scarce any
place, but Cod, Cuske, Holybut, Mackerell, Scate, or such like, a man
may take with a hooke or line what he will. And, in diverse sandy
Baies, a man may draw with a net great store of Mullets, Bases, and
diverse other sorts of such excellent fish, as many as his Net can
drawe on shore: no River where there is not plentie of Sturgion, or
Salmon, or both; all which are to be had in abundance observing but
their seasons. But if a man will goe at Christmasse to gather
Cherries in Kent, he may be deceived; though there be plentie in
Summer: so, heere these plenties have each their seasons, as I have
expressed. We for the most part had little but bread and vinegar:
and though the most part of Iuly when the fishing decaied they
wrought all day, laie abroade in the Iles all night, and lived on what
they found, yet were not sicke: But I would wish none put himself
long to such plunges; except necessitie constraine it: yet worthy is
that person to starve that heere cannot live; if he have sense,
strength and health: for there is no such penury of these blessings in
any place, but that a hundred men may, in one houre or two, make
their provisions for a day: and hee that hath experience to manage
well these affaires, with fortie or thirtie honest industrious men,
might well undertake (if they dwell in these parts) to subiect the
Salvages, and feed daily two or three hundred men, with as good
corne, fish and flesh, as the earth hath of those kindes, and yet
make that labor but their pleasure: provided that they have engins,
that be proper for their purposes.
Who can desire more content, that hath small meanes; or but only
his merit to advance his fortune, then to tread, and plant that
ground hee hath purchased by the hazard of his life? If he have but
the taste of virtue, and magnanimitie, what to such a minde can bee
more pleasant, then planting and building a foundation for his
Posteritie, gotte from the rude earth, by Gods blessing and his owne
industrie, without prejudice to any? If hee have any graine of faith or
zeale in Religion, what can hee doe lesse hurtfull to any; or more
agreeable to God, then to seeke to convert those poore Salvages to
know Christ, and humanitie, whose labors with discretion will triple
requite thy charge and paines? What so truely sutes with honour
and honestie, as the discovering things unknowne? erecting Townes,
peopling Countries, informing the ignorant, reforming things unjust,
teaching virtue; and gaine to our Native mother-countrie a kingdom
to attend her; finde imployment for those that are idle, because they
know not what to doe: so farre from wronging any, as to cause
Posteritie to remember thee; and remembering thee, ever honour
that remembrance with praise?
 Thomas Dermer

1619

MAINE AND CAPE COD

Thomas Dermer made his first voyage to New England in 1615.
The following year he sailed to Newfoundland, where he may
have remained until late in 1618. In 1619 he visited New
England again, going from there to Virginia. He wrote an
account of this voyage for Samuel Purchas, who printed it in
the fourth volume of “Purchas his Pilgrimes,” published at
London in 1625.
Dermer’s account of another voyage northward from
Virginia, in the course of which he found divers ships from
Amsterdam and Horne trading with the natives on the
Delaware and Hudson rivers, was presented to the Virginia
Company in London, on July 10, 1621.
 To his Worshipfull Friend M. Samvel Pvrchas,
Preacher of the Word, at the Church a little
within Ludgate, London.

Sir,

IT was the nineteenth of May, before I was fitted for 1619 May
my discouery, when from Monahiggan I set sayle in an
open Pinnace of fiue tun, for the Iland I told you of. I Monhegan
passed alongst the Coast where I found some antient
Plantations, not long since populous now vtterly void; in other places
a remnant remaines, but not free of sicknesse. Their disease the
Plague, for wee might perceiue the sores of some that had escaped,
who described the spots of such as vsually die. When I arriued at my
Sauages natiue Country (finding all dead) I trauelled alongst a daies
iourney Westward, to a place called Nummastaquyt, where finding
Inhabitants, I dispatched a Messenger a dayes iourney further West,
to Poconaokit which bordereth on the Sea; whence came to see me
two Kings, attended with a guard of fiftie armed men, who being
well satisfied with that my Sauage and I discoursed vnto them
(being desirous of noueltie) gaue mee content in whasoeuer I
demanded, where I found that former relations were true. Here I
redeemed a Frenchman, and afterwards another at Mastachusit,
who three yeeres since escaped shipwracke at the North-east of
Cape Cod. I must (amongst many things worthy obseruation) for
want of leisure, therefore hence I passe (not mentioning any place
where we touched in the way) to the Iland, which wee discouered
the twelfth of Iune. Here we had good quarter with June
the Sauages, who likewise confirmed former reports. I
found seuen seuerall places digged, sent home of the earth, with
samples of other commodities elsewhere found, sounded the Coast,
and the time being farre spent bare vp for Monahiggan, arriuing the
three and [twen]tieth of Iune, where wee found our Ship ready to
depart. To this Ile are two other neere adioyning, all which I called
by the name of King Iames his Iles, because from thence I had the
first motiues to search. For that (now probable passage) which may
hereafter be both honourable and profitable to his Maiestie. When I
had dispatched with the ships ready to depart, I thus concluded for
the accomplishing my businesse. In regard of the fewnesse of my
men, not being able to leaue behind mee a competent number for
defence, and yet sufficiently furnish my selfe, I put most of my
prouisions aboord the Sampson of Cape Ward ready bound for
Virginia, from whence hee came, taking no more into the Pinnace
then I thought might serue our turnes, determining with Gods helpe
to search the Coast along, and at Virginia to supply our selues for a
second discouery, if the first failed. But as the best actions are
commonly hardest in effecting and are seldome without their
crosses, so in this we had our share, and met with many difficulties:
for wee had not sayled aboue forty leagues, but wee were taken
with a Southerly storme, which draue vs to this strait; eyther we
must weather a rockie point of Land, or run into a broad Bay no
lesse dangerous; Incidit in Syllam, &c. the Rockes wee could not
weather, though wee loosed till we receiued much water, but at last
were forced to beare vp for the Bay, and run on ground a furlong off
the shoare, where we had beene beaten to pieces, had wee not
instantly throwne ouerboord our prouisions to haue our liues; by
which meanes we escaped and brought off our Pinnace the next
high water without hurt, hauing our Planke broken, and a small
leake or two which we easily mended. Being left in this misery,
hauing lost much bread, all our Beefe and Sider, some Meale and
Apparell, with other prouisions and necessaries; having now little left
besides hope to encourage vs to persist: Yet after a little deliberation
we resolued to proceed and departed with the next faire winde. We
had not now that faire quarter amongst the Sauages as before,
which I take it was by reason of our Sauages absence, who desired
(in regard of our long iourney) to stay with some of our Sauage
friends at Sawahquatooke, for now almost euery where, where they
were of any strength they sought to betray vs. At Manamock (the
Southerne part of Cape Cod, now called Sutcliffe Monomoy
Inlets) I was vnawares taken prisoner, when they
sought to kill my men, which I left to man the Pinnace; but missing
of their purpose, they demanded a ransome, which had, I was as
farre from libertie as before; yet it pleased God at last, after a
strange manner to deliuer me, with three of them into my hands,
and a little after the chiefe Sacheum himselfe; who seeing me weigh
anchor, would haue leaped ouerboord, but intercepted, craued
pardon, and sent for the Hatchets giuen for ransome, excusing
himselfe by laying the fault on his neighbours; and to be friends sent
for a Canoas lading of Corne, which receiued we set him free. I am
loth to omit the story, wherein you would finde cause to admire the
great mercy of God euen in our greatest misery, in giuing vs both
freedome and reliefe at one time. Departing hence, the next place
we arriued at was Capaock, an Iland formerly discouered by the
English, where I met with Epinew a Sauage that had liued in
England, and speakes indifferent good English, who foure yeeres
since being carried home, was reported to haue beene slaine, with
diuers of his Countreymen, by Saylors, which was false. With him I
had much conference, who gaue mee very good satisfaction in euery
thing almost I could demand. Time not permitting mee to search
here, which I should haue done for sundry things of speciall
moment: the wind faire, I stood away shaping my course as the
Coast led mee, till I came to the most Westerly part where the Coast
began to fall away Southerly. In my way I discouered Land about
thirtie leagues in length, heretofore taken for Mayne, Martha’s Vineyard
where I feared I had beene imbayed, but by the helpe
of an Indian I got to the Sea againe, through many crooked and
streight passages. I let passe many accidents in this iourney
occasioned by treacherie, where wee were compelled twice to goe
together by the eares, once the Sauages had great advantage of vs
in a streight, not aboue a Bowe shot, and where a multitude of
Indians let flye at vs from the banke, but it pleased God to make vs
victours: neere vnto this wee found a most dangerous Catwract
amongst small rockie Ilands, occasioned by two vnequall tydes, the
one ebbing and flowing two houres before the other: here wee lost
an Anchor by the strength of the current, but found it deepe
enough: from hence were wee carried in a short space by the tydes
swiftnesse into a great Bay (to vs so appearing) but indeede is
broken land, which gaue vs light of the Sea: here, as I said, the
Land treadeth Southerly. In this place I talked with many Saluages,
who told me of two sundry passages to the great Sea on the West,
offered me Pilots, and one of them drew mee a Plot Long Island Sound
with Chalke vpon a Chest, whereby I found it a great
Iland, parted the two Seas; they report the one scarce passable for
shoalds, perillous currents, the other no question to be made of.
Hauing receiued these directions, I hastened to the place of greatest
hope, where I purposed to make triall of Gods goodnesse towards
vs, and vse my best endeuour to bring the truth to light, but wee
were but onely shewed the entrance, where in seeking to passe wee
were forced backe with contrary and ouerblowing windes, hardly
escaping both our liues. Being thus ouercharged with weather, I
stood alongst the coast to seeke harbours, to attend a fauourable
gale to recouer the streight, but being a harbourlesse Coast for
ought we could then perceiue, wee found no succour till wee arriued
betwixt Cape Charles and the Maine on the East side the Bay
Chestapeake, where in a wilde Roade wee anchored; Chesapeake Bay
and the next day (the eight of September) crossed the
Bay to Kecoughtan, where the first newes strooke cold to our hearts,
the general sicknesse ouer the Land. Here I resolued with all
possible speede to returne in pursuite of this businesse, so that after
a little refreshing, wee recouered vp the Riuer to Iames Citie, and
from thence to Cape Warde his Plantacon, where immediately wee
fell to hewing of Boords for a close Decke, hauing found it a most
desired course to attempt as before. As wee were thus labouring to
effect our purposes, it pleased almighty God (who onely disposeth of
the times and seasons, wherein all workes shall be accomplished) to
visite vs with his heauie hand, so that at one time there were but
two of vs able to helpe the rest, my selfe so sore shaken with a
burning feauer, that I was brought euen vnto deaths doore, but at
length by Gods assistance escaped, and haue now with the rest
almost recouered my former strength. The Winter hauing ouertaken
vs (a time on these Coasts especially) subiect to gusts and fearefull
storms, I haue now resolued to choose a more temperate season,
both for the generall good and our owne safeties. And thus I haue
sent you a broken discourse, though indeede very vnwilling to haue
giuen any notice at all, till it had pleased God to haue blessed mee
with a thorow search, that our eyes might haue witnessed the truth.
I haue drawne a Plot of the Coast, which I dare not yet part with for
feare of danger, let this therefore serue for confirmation of your
hopes, till I can better performe my promise and your desire; for
what I haue spoken I can produce at least mille testes; farre
separate, of the Sea behinde them, and of Ships, which come many
dayes iourney from the West, and of the great extent of this Sea to
the North and South, not knowing any bounds thereof Westward. I
cease to trouble you till a better opportunity offer it selfe,
remembring my best loue, &c. I rest
Yours to command,
Tho. Dermer.
From Captaine Martyn his Plantation.
27 Decemb. 1619.
 Christopher Levett

1624

YORK AND PORTLAND

Christopher Levett, who was born in York, England, in 1586,
landed on the Isles of Shoals in the autumn of 1623. Finding
that this was no place for a permanent settlement, he crossed
to the mouth of the Piscataqua River, where Robert Gorges,
who had recently been appointed governor of the territory
granted to the Council for New England, was making his
colonial headquarters. Levett had been given the right to
settle and hold six thousand acres wherever he might choose
to locate within this territory. He selected an island at the
mouth of Portland harbour. There he left ten men to maintain
his possession while he went back to England for recruits and
supplies. To assist in securing these, he wrote an account of
the country and of his adventures therein, which he doubtless
intended to print as soon as he returned home. A variety of
causes hindered the carrying out of his plans, and the book
was not published until 1628. The chapters now reprinted are
those which contain the account of his experiences in New
England. These chapters, as well as the extracts from Purchas
and other works not otherwise credited, are taken from the
copies of the original editions in the John Carter Brown
Library at Providence, Rhode Island.
 My Discouery of diverse Riuers and Harbours,
with their names, and which are fit for
Plantations, and which not.

THE first place I set my foote vpon in New England, 1623

was the Isles of Shoulds, being Ilands in the Sea,
about two Leagues from the Mayne.
Vpon these Ilands, I neither could see one good timber tree, nor
so much good ground as to make a garden.
The place is found to be a good fishing place for 6 Shippes, but
more cannot well be there for want of convenient stage-roome, as
this yeare’s experience hath proved.
The Harbor is but indifferent good. Vpon these Ilands are no
Savages at all.
The next place I came vnto was Pannaway, where Piscataqua River
one M. Tomson hath made a Plantation, there I stayed
about one Moneth in which time I sent for my men from the East:
who came over in diverse Shipps.
At this place I met with the Governour, who came thither in a
Barke which he had from one M. Weston about 20 dayes before I
arived in the Land.
The Governour then told me that I was joyned with him in
Commission as a Counsellor, which being read I found it was so. And
he then, in the presence of three more of the Counsell, administered
unto me an oath.
 After the meeting of my men, I went a coasting in two boats with
all my company.
In the time I stayd with M. Tomson, I surveyed as much as
possible I could, the wether being vnseasonable, and very much
snow.
In those parts I saw much good Timber. But the ground it seemed
to me not to be good, being very rockey and full of trees and brush-
wood.
There is great store of fowle of diverse sorts, wherof I fed very
plentifully.
About two English miles further to the East, I found a great River
and a good harbour called Pascattaway. But for the ground I can say
nothing, but by the relation of the Sagamore or King of that place,
who told me there was much good ground up in the river about
seven or eight leagues.
About two leagues further to the East, is another great river called
Aquamenticus. There I think a good plantation may be York River
settled, for there is a good harbour for ships, good
ground, and much already cleared, fit for planting of corne and other
fruits, having heretofore ben planted by the Salvages who are all
dead. There is good timber, and likely to be good fishing, but as yet
there hath beene no tryall made that I can heare of.
About 6 leagues further to the East is a harbour called Cape
Porpas, the which is indifferent good for 6 shippes, and it is
generally thought to be an excellent place for fish, but as yet there
hath been no tryall made, but there may be a good plantation
seated, for there is good Timber and good ground, but will require
some labour and charge.
About foure leagues further East, there is another harbour called
Sawco (betweene this place and Cape Porpas I lost one of my men)
before we could recover the harbour a great fog or mist tooke us
that we could not see a hundred yards from us. I perceiving the fog
to come upon the Sea, called for a Compasse and set the Cape land,
by which wee knew how to steare our course, which was no sooner
done but wee lost sight of land, and my other boate, and the winde
blew fresh against us, so that we were enforced to strike saile and
betake us to our Oares which wee used with all the wit and strength
we had, but by no meanes could we recover the shore that night,
being imbayed and compassed round with breaches, which roared in
a most fearfull manner on every side us; wee took counsell in this
extremity one of another what to doe to save our lives, at length we
resolved that to put to sea againe in the night was no fit course, the
storme being great, and the winde blowing right of the shore, and to
runne our boate on the shore amongst the breaches, (which roared
in a most fearefull manner) and cast her away and indanger
ourselves we were loath to do, seeing no land nor knowing where
we were. At length I caused our Killick (which was all the Anker we
had) to be cast forth, and one continually to hold his hand upon the
roode or cable, by which we knew whether our ancker held or no:
which being done wee commended our selues to God by prayer, &
put on a resolution to be as comfortable as we could, and so fell to
our victuals. Thus we spent that night, and the next morning, with
much adoe we got into Sawco, where I found my other boate.
There I stayed fiue nights, the winde beinge contrary, and the
weather very unseasonable, hauing much raine and snow, and
continuall foggse.
We built us our Wigwam, or house, in one houres space, it had no
frame, but was without forme or fashion, onely a few poles set up
together, and couered with our boates sailes which kept forth but a
little winde, and lesse raigne and snow.
Our greatest comfort we had, next unto that which was spirituall,
was this we had foule enough for killing, wood enough for felling,
and good fresh water enough for drinking.
But our beds was the wet ground, and our bedding our wet
cloaths. Wee had plenty of Craine, Goose, Duckes and Mallard, with
other fowle, both boyled and rosted, but our spits and racks were
many times in danger of burning before the meate was ready (being
but wooden ones.)
After I had stayed there three daies, and no likelyhood of a good
winde to carrie vs further, I tooke with me six of my men, and our
Armes, and walked along the shore, to discouer as much by land as
I could: after I had travelled about two English miles I met with a
riuer which stayed me that I could goe no further by land that day,
but returned to our place of habitation where we rested that night
(hauing our lodging amended) for the day being dry I caused all my
company to accompany mee to a marsh ground, where wee
gathered euery man his burthen of long dry grasse, which being
spread in our Wigwam or House, I praise God I rested as
contentedly as euer I did in all my life. And then came into my
minde an old merry saying, which I haue heard of a beggar boy,
who said if euer he should attaine to be a King, he would haue a
breast of mutton with a pudding in it, and lodge euery night vp to
the eares in drye straw; and thus I made myselfe and my company
as merry as I could, with this and some other conceits, making this
vse of all, that it was much better then wee deserued at Gods
hands, if he should deale with vs according to our sinnes.
The next morning I caused 4 of my men to rowe my lesser boate
to this riuer, who with much adoe got in myselfe, and 3 more going
by land: but by reason of the extremitie of the wether we were
enforced to stay there that night, and were constrained to sleepe
vpon the riuer banke, being the best place wee could finde, the
snowe being very deepe.
The next morning wee were enforced to rise betime, for the tyde
came vp so high that it washed away our fire, and would haue
serued vs so too if we had not kept watch: So wee went over the
riuer in our boate, where I caused some to stay with her, myselfe
being desirous to discouer further by land, I tooke with me foure
men and walked along the shore about sixe English miles further to
the East, where I found another riuer, which staied mee. So we
returned backe to Sawco, where the rest of my company and my
other boate lay. That night I was exceeding sicke, by reason of the
wet and cold and much toyling of my body: but thankes be to God I
was indifferent well the next morning, and the winde being faire we
put to sea, and that day came to Quack.
But before I speak of this place I must say something of Sawco,
and the too riuers which I discouered in that bay, Saco
which I thinke neuer Englishman saw before.
Sawco is about one league to the North-east of a cape land. And
about one English mile from the maine lieth sixe Ilands, which make
an indifferent good harbour. And in the maine there is a Coue or
gutt, which is about a cables length in bredth, and too cables length
long, there two good Ships may ride, being well mored a head and
starne; and within the Coue there is a great Marsh, where at a high
water a hundredth sayle of Ships may floate, and be free from all
winds, but at low water must ly a ground, but being soft oase they
can take no hurte.
In this place there is a world of fowle, much good timber, and a
great quantetie of cleare ground and good, if it be not a little too
sandy. There hath beene more fish taken within too leagues of this
place this yeare then in any other in the land.
The riuer next to Sawco eastwards, which I discovered by land,
and after brought my boat into, is the strangest river that ever my
eyes beheld. It flowes at the least ten foot water upright, and yet
the ebbe runs so strong that the tyde doth not stem it. At three
quarters floud my men were scarce able with foure Oares to rowe
ahead. And more then that, at full Sea I dipped my hand in the
water, quite without the mouth of the River, in the very main Ocean,
and it was as fresh as though it had been taken from the head of a
Spring.
This River, as I am told by the Salvages, commeth from a great
mountaine called the Christall hill, being as they say 100 miles in the
Country, yet is it to be seene at the sea side, and there is no ship
ariues in New England, either to the West so farre as Cape Cod, or
to the East so farre as Monhiggen, but they see this Mountaine the
first land, if the weather be cleere.
The next river Eastward which I discovered by land, is about sixe
miles from the other. About these two riuers I saw much good
timber and sandy ground, there is also much fowle, fish and other
commodities: but these places are not fit for plantation for the
present, because there is no good comming in, either for ship, or
boate, by reason of a sandy breach which lyeth alongst the shore,
and makes all one breach.
And now in its place I come to Quack, which I haue named Yorke.
At this place there fished divers ships of Waymouth this yeare.
It lyeth about two leagues to the East of Cape Elizabeth. It is a
Bay or Sound betwixt the Maine and certaine Ilands Portland Harbour
which lyeth in the sea about one English mile and
halfe.
There are foure Ilands which makes one good harbour, there is
very good fishing, much fowle and the mayne as good ground as
any can desire. There I found one River wherein the Savages say
there is much Salmon and other good fish. In this Bay, there hath
ben taken this yeare 4. Sturgions, by fishermen who driue only for
Herrings, so that it is likely there may be good store taken if there
were men fit for that purpose. This River I made bold to call by my
owne name Levetts river, being the first that Fore River
discovered it. How farre this river is Navigable I
cannot tell, I haue ben but 6. miles up it, but on both sides is goodly
ground.
In the same Bay I found another River, up which I Presumpscot River
went about three miles, and found a great fall, of
water much bigger than the fall at London bridge, at low water;
further a boate cannot goe, but above the fall the River runnes
smooth againe.
Iust at this fall of water the Sagamore or King of that place hath a
house, where I was one day when there were two Sagamors more,
their wiues and children, in all about 50. and we were but 7. They
bid me welcome and gaue me such victualls as they had, and I gaue
them Tobacco and Aqua vitæ.
After I had spent a little time with them I departed & gaue them a
small shot, and they gaue me another. And the great Sagamore of
the East country, whom the rest doe acknowledge to be chiefe
amongst them, hee gaue unto me a Bevers skin, which I thankfully
received, and so in great loue we parted. On both sides this river
there is goodly ground.
From this harbour to Sagadahock, which is about 8. or 9. leagues,
is all broken Ilands in the Sea, which makes many excellent good
Harbours, where a thousand saile of Shipps may ride in safety; the
sound going up within the Ilands to the Cape of Sagadahock.
In the way betwixt Yorke and Sagadahock lyeth Cascoe, a good
harbour, good fishing, good ground, and much fowle. Casco Bay
And I am perswaded that from Cape Elizabeth to
Sagadahock, which is aboue 30 leagues to follow the Maine, is all
exceeding commodious for Plantations: and that there may be 20
good Townes well seated, to take the benefit both of the sea, and
fresh Rivers.
For Sagadahock I need say nothing of it, there hath been
heeretofore enough said by others, and I feare me too much. But
the place is good, there fished this yeare two ships.
The next place I came to was Capemanwagan, a Boothbay
place where nine ships fished this yeare. But I like it
not for a plantation, for I could see little good timber & lesse good
ground, there I stayed foure nights, in which time, there came many
Savages with their wiues and children, and some of good accompt
amongst them, as Menarwormet a Sagamore, Cogawesco the
Sagamore of Casco and Quack, now called Yorke, Somerset, a
Sagamore, one that hath ben found very faithfull to the English, and
hath saved the liues of many of our Nation, some from starving,
others from killing.
 They entended to haue ben gone presently, but hearing of my
being there, they desired to see me, which I understood by one of
the Masters of the Ships, who likewise told me that they had some
store of Beauer coats and skinnes, and was going to Pemaquid to
truck with one Mr. Witheridge, a Master of a ship of Bastable, and
desired me to use meanes that they should not carry them out of
the harbour, I wisht them to bring all their truck to one Mr. Cokes
stage, & I would do the best I could to put it away: some of them
did accordingly, and I then sent for the Sagamores, who came, and
after some complements they told me I must be their cozen, and
that Captaine Gorges was so, (which you may imagine I was not a
little proud of, to be adopted cozen to so many great Kings at one
instant, but did willingly accept of it) and so passing away a little
time very pleasantly, they desired to be gone, whereupon I told
them that I understood they had some coates and Beauers skins
which I desired to truck for but they were unwilling, and I seemed
carelesse of it (as men must doe if they desire any thing of them.)
But at last Somerset swore that there should be none carryed out of
the harbour, but his cozen Levett should haue all, and then they
began to offer me some by way of gift, but I would take none but
one paire of sleeues from Cogawesco, but told them it was not the
fashion of English Captaines alwaies to be taking, but sometimes to
take and giue, and continually to truck was very good. But in fine,
we had all except one coate and two skinnes, which they reserved to
pay an old debt with, but they staying all that night, had them stole
from them.
In the morning the Sagamores came to mee with a grieuous
complaint, I vsed the best language I could to giue them content,
and went with them to some Stages which they most suspected, and
seached both Cabins and Chests, but found none. They seeing my
willingnesse to finde the theefe out, gaue mee thankes, and wished
me to forbeare saying the Rogues had carried them into the woods
where I could not find them.
When they were ready to depart they asked mee where I meant
to settle my plantation. I told them I had seene many places to the
west, and intended to goe farther to the east before I could resolue,
they sayed there was no good place, and I had heard, that
Pemoquid and Capmanwagan, and Monhiggon were granted to
others, & the best time for fishing was then at hand, which made me
the more willing to retire, and the rather because Cogawesco, the
Sagamore of Casco and Quacke, told me if that I would sit downe at
either of those two places, I should be very welcome, and that he
and his wife would goe along with me in my boate to see them,
which curtesy I had no reason to refuse, because, I had set vp my
resolution before to settle my plantation at Quacke, which I named
Yorke, and was glad of this oppertunity, that I had obtained the
consent of them who as I conceiue hath a naturall right of
inheritance, as they are the sonnes of Noah, and therefore doe
thinke it fit to carry things very fairely without compulsion, (if it be
posible) for avoyding of treacherie.
The next day the winde came faire, and I sayled to Quacke or
Yorke, with the King, Queene, and Prince, bowe and arrowes, dogge
and kettell in my boate, his noble attendance rowing by vs in their
Cannow.
When we came to Yorke the Masters of the Shippes came to bid
me welcome, and asked what Sauages those were, I told them, and
I thanked them, they vsed them kindly, & gaue them meate, drinke
and tobacco. The woman or reputed Queene, asked me if those men
were my friends, I told her they were; then she dranke to them, and
told them, they were welcome to her Countrey, and so should all my
friends be at any time, she dranke also to her husband, and bid him
welcome to her Countrey too, for you must vnderstand that her
father was the Sagamore of this place, and left it to her at his death
hauing no more Children.
And thus after many dangers, much labour and great charge, I
haue obtained a place of habitation in New-England, where I haue
built a house, and fortified it in a reasonable good fashion, strong
enough against such enemies as are those Sauage people.
How the Sauages carried themselues vnto me
continually, and of my going to their Kings Houses:
and their comming to mine.

WHILEST I staied in this place I had some little trucke, but not
much, by reason of an euill member in the Harbour, who being
couetous of trucke vsed the matter so, that he got the Sauages
away from me.
And it is no wonder that he should abuse me in this sort, for he
hath not spared your Lordshipps and all the Counsell for New-
England.
He said vnto the Gouernour that the Lords had sent men ouer into
that Countrey with Commissions, to make a prey of others. And yet
for my owne part I neuer demanded or tooke from any man in that
Countrey, the value of a denier neither had I so much helpe, from
any Shippe or Shippes companie as one mans labour the space of an
houre, nor, had I any prouision or victuall vpon any tearmes
whatsoeuer, saue onely 1000. of bread, and 22. bushells of pease,
which was offered vnto mee and not by me requested, for which I
gaue present satisfaction in Beuer skines: and also one Rownlet of
Aqua vitæ, which was brought to me 16 Leagues vnexpected, which
good manners bid me buy. Much more provision was offered to me
by many Masters of Ships, but I had no need thereof, so I gaue
them thanks for their kindnesse, and refused all.
Nay, it is well knowne, that I was so farre from doing wrong to
any: that I suffered the Land which was granted to me by Pattent
and made choyce of before any other man came there, to be used,
and my timber to be cut downe & spoyled, without taking or asking
any satisfaction for the same. And I doubt not but all others to
whom you gaue authoritie, will sufficiently cleare themselues of all
such imputations.
He said also he cared not for any authoritie in that place and
though he was forbid to trucke yet would he haue all he could get:
in despite of who should say to the contrary, having a great Ship
with 17. peeces of Ordinance and 50. men.
And indeed his practise was according to his words, for every
Sunday or once in the weeke, he went himselfe or sent a boate up
the river and got all the trucke before they could come downe to the
Harbour. And so many Savages as he could get to his stage, hee
would enforce them to leaue their goods behind them. One instance
a mongst many I will giue you.
On a certaine day there came two Savages to his place, who were
under the command of Somerset or Conway, I know not whether, at
which time they were both with me at my house, but the other two
who went to him, knew not so much, but afterwards they
understanding of it, came presently over, but left their Cotts and
Beauer skins behind them, whereat Somerset and Conway were
exceeding angrie and were ready to beate the poore fellows, but I
would not suffer them so to doe. They presently went over the
Harbor themselues in their Cannow to fetch their goods, but this
man would let them haue none, but wished them to truck with him,
they told him they would not, but would carry them to Captaine
Levett, he said Levett was no captaine, but a Iacknape, a poore
fellow, &c. They told him againe that he was a Roague, with some
other speeches, whereupon he and his company fell upon them &
beate them both, in so much that they came to me in a great rage
against him, and said they would be revenged on his Fishermen at
sea, and much adoe I had to diswade one of them for going into
England to tell King James of it, as he said; when they came to me
in this rage, there was two or three Masters of Shippes by, and
heard every word.
But all this did me no hurt, (saue the losse of the trucke, which by
divers was thought to be worth above 50. li.) for the two Sagamores
whom he inticed from me, and incensed against me, at length used
meanes to be freinds with me, sending one who asked me, if I were
angrie with them, I told them no, I was not angrie with them for any
such matter as lowsie Cotts and skinnes, but if they were Matchett,
that is, naughtie men, and rebellious, then I would be Mouchick
Hoggery, that is very angry, and would Cram, that is, kill them all.
When they came them selues to me to seeke peace, they brought
me a Beauer Coate, and two Otter skines, which they would have let
me had for nothing, but I would not take them so, but gaue them
more then vsually I did by way of Trucke, I then told them likewise
that if at any time they did Trucke with mee, they should haue many
good things in leiu of their Beauer: and if they did not Trucke it was
no matter, I would be good friends with them, at which they smiled
and talked one to the other, saying the other man was a Iacknape,
and that I had the right fashion of the Aberieney Sagamores, then
they began to applaude or rather flatter me, saying I was so bigge a
Sagamore, yea foure fathom, which were the best words they could
vse to expresse their minds: I replied that I was a poore man as he
had reported of mee. They said againe it was no matter what I said,
or that Iacknape (which is the most disgracefull word that may be in
their conceite,) for all the Sagamores in the Country loued poore
Levett and was Muchicke sorrie that he would be gon, and indeed I
cannot tell what I should thinke of them, for euer after they would
bring mee any thing they thought would giue mee content, as Egges
and the whole bodyes of Beauer, which in my concite eate like
Lambe, and is not inferiour to it: yea the very coats of Beauer &
Otter-skinnes from off their backes, which though I many time
refused, yet not allwaies, but I neuer tooke any such courtesie from
them, but I requited them answerably, chusing rather to neglect the
present profit, then the hopes I haue to bring them to better things,
which I hope will be for a publicke good, and which I am perswaded
were a greeuous sinne, to neglect for any sinister end.
And a little before my departure there came these Sagamores to
see mee, Sadamoyt, the great Sagamore of the East Countrey,
Manawormet, Opparunwit, Skedraguscett, Cogawesco, Somersett,
Conway and others.
They asked me why I would be gone out of their Countrey, I was
glad to tell them my wife would not come thither except I did fetch
her, they bid a pox on her hounds, (a phrase they have learned and
doe vse when they doe curse) and wished me to beate her. I told
them no, for then our God would bee angrie. Then they runne out
vpon her in euil tearmes, and wished me to let her alone and take
another, I told them our God would be more angrie for that. Againe
they bid me beate her, beate her, repeating it often, and very
angerly, but I answered no, that was not the English fashion, and
besides, she was a good wife and I had children by her, and I loued
her well, so I satisfied them. Then they told me that I and my wife
and Children, with all my friends, should bee hartily welcome into
that Countrey at any time, yea a hundreth thousand times, yea
Mouchicke, Mouchicke, which is a word of waight.
And Somersett tould that his Sonne (who was borne, whilst I was
in the Countrey, and whom hee would needs haue to Name) and
mine should be Brothers and that there should be muchicke
legamatch, (that is friendship) betwixt them, untill Tanto carried
them to his wigwam, (that is vntill that they died.)
Then they must know of mee how long I would be wanting, I told
them so many Months, at which they seemed to be well pleased, but
wisht me to take heede I proued not Chechaske in that (that is, a
lier.) They asked me what I would doe with my house, I told them I
would leaue 10. of my men there vntill I came againe, and that they
should kill all the Tarrantens they should see (being enimies to
them) and with whom the English haue no commarsse. At which
they reioyced exceedingly, and then agreed amongst themselues
that when the time should be expired, which I spoke of for my
returne, euery one at the place where he liued would looke to the
Sea, and when they did see a Ship they wold send to all the
Sagamores in the Countrey, and tell them that poore Levett was
come againe. And thus insteed of doing me hurt, I thinke that either
he or I haue done good to all Planters, by winning their affections,
(which may bee made vse of without trusting of them.)
But if your Lordship should put up this wrong done unto you, and
the Authority which you gaue them, never expect to be obeyed in
those parts, either by Planters or Fishermen; for some haue not
stucke to say, that if such a man, contemning authority, and abusing
one of the counsell, and drawing his knife upon him at his own
house, which he did, should goe unpunished, then would not they
care what they did heereafter.
And truely let me tell your Lordships, that if euer you intend to
punish any for disobedience, or contempt of authority, this man is a
fit instrument to make a president of, for he is rich, and this yeare
will gaine the best part of 500 pounds by that Countrie, and he hath
nether wife nor childe, for whose sakes he should be spared.
And if he goe free, as hee has domineered over vs, to whom your
Lordships gaue authority, but no power to put it in execution, so will
he grow unmannerly too with your Lordships, as hee hath already
begunne.
And it will discourage men hereafter to take any authority upon
them, or to goe about to reforme any abuses in those parts, and
also it will hinder Planters for going over, if Fishermen be suffered
not onely to take away their truck, but also to animate the Sauages
against them, for this is the way to cause all Planters to haue their
throats cut.
But I leaue these things to your Lo. consideration, who haue as
well power as authority to punish such rebellious persons.
Thus hauing acquainted you with what I haue done, seen and
heard; now giue me leaue to tell you what I thinke of the Savages,
the inhabitants of that country: as also to iustifie the innocent, I
meane the Countrie of New-England, against the slanderous reports
of this man, and some others which I haue heard, and likewise to
deliver my opinion, what courses I conceiue to be most convenient
to be taken, for bringing most glorie to God, comfort, honor and
benefit to our King, and our owne Natiue Nation.

The nature and disposition of the Savages, and of

their severall Gods, Squanto and Tanto.

I HAUE had much conference with the Savages, about our only true
God, and haue done my best to bring them to know and
acknowledge him, but I feare me all the labour that way, will be lost,
and no good will be done, except it be among the younger sort.
I find they haue two Gods, on they love: and the other they hate:
the god they loue, they call Squanto, and to him they ascribe all
their good fortunes.
The god they hate they call Tanto, and to him they ascribe all their
euill fortunes, as thus, when any is killed, hurt or sicke, or when it is
evill wether, then they say Tanto is hoggry, that is angry. When any
dyes, they say Tanto carries them to his wigwam, that is his house,
and they never see them more.
I haue asked them where Squanto dwells, they say they cannot
tell but up on high, and will poynt upwards. And for Tanto, they say
farre west, but they know not where.
I haue asked them if at any time they haue seene Squanto, or
Tanto, they say no, there is none sees them, but their Pawwawes,
nor they neither, but when they dreame.
Their Pawwawes are their Phisitians and Surgions, and as I verely
beleeue they are all Witches, for they foretell of ill wether, and many
strange things, every Sagamore hath one of them belongs to his
company, and they are altogether directed by them.
On a time I was at a Sagamores house and saw a Martins skin,
and asked if he would trucke it, the Sagamore told me no, the
Pawwawe used to lay that under his head when he dreamed, and if
he wanted that, he could doe nothing, thus we may perceiue how
the devill deludes those poore people and keep them in blindnesse.
I find them generally to be marvellous quicke of apprehension,
and full of subteltie, they will quickely find any man’s disposition,
and flatter & humour him strangely, if they hope to get anything of
him. And yet will they count him a foole if he doe not shew a dislike
of it, and will say on to another, that such a man is a Mechecome.
They are slow of speech, and if they heare a man speake much
they will laugh at him, and say he is a Mechecum, that is a foole.
If men of place be to familiar with them, they will not respect
them: therefore it is to be wished that all such persons should be
wise in their Carriage.
The Sagamores will scarce speake to an ordinary man, but will
point to their men, and say Sanops, must speake to Sanops, and
Sagamors to Sagamors.
They are very bloudy minded and full of Tracherie amongst
themselues, one will kill another for their wiues, and he that hath
the most wiues is the brauest fellow: therefore I would wish no man
to trust them, what euer they say or doe; but alwaies to keepe a
strickt hand ouer them, and yet to vse them kindly, and deale
vprightly with them; so shall they please God, keepe their reputation
amongst them, and be free from danger.
Their Sagamors are no Kings, as I verilie beleeue, for I can see no
Government or Law amongst them but Club Law: and they call all
Masters of Shippes Sagamore, or any other man, that they see have
a commaund of men.
Their wiues are their slaves, and doe all their worke the men will
doe nothing but kill Beasts, Fish, &c.
On a time reasoning with one of their Sagamors about their
hauing so many wiues, I tould him it was no good fashion, he then
asked mee how many wiues King James had, I told him he neuer
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

ebooknice.com