WWW.K2PDF.COM TRIAL Metro Modular Content Framework and Document Format
Specification and Reference Guide © 2005 Microsoft Corporation. All rights reserved. Information in these materials is restricted to Microsoft authorized recipients only. Any use, distribution or public discussion of, and any feedback to, these materials is subject to the terms of the attached license. By providing any feedback on these materials to Microsoft, you agree to the terms of that license. If the license agreement has been removed, review the terms at http://www.microsoft.com/whdc/device/print/metro.mspx before using these materials.
Version 0.7
Version
0.7
Status
Final
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL ii
Metro Specification and Reference Guide
Microsoft Corporation Technical Documentation License Agreement for the specification code named "Metro"
READ THIS! THIS IS A LEGAL AGREEMENT BETWEEN MICROSOFT CORPORATION ("MICROSOFT") AND THE RECIPIENT OF THE ABOVE REFERENCED MATERIALS, WHETHER AN INDIVIDUAL OR AN ENTITY ("YOU"). IF YOU HAVE ACCESSED THIS AGREEMENT IN THE PROCESS OF DOWNLOADING THESE MATERIALS ("MATERIALS") FROM A MICROSOFT WEB SITE, BY CLICKING "I ACCEPT", DOWNLOADING, USING OR PROVIDING FEEDBACK ON THE MATERIALS, YOU AGREE TO THESE TERMS. IF THIS AGREEMENT IS ATTACHED TO MATERIALS, BY ACCESSING, USING OR PROVIDING FEEDBACK ON THE ATTACHED MATERIALS, YOU AGREE TO THESE TERMS. IF YOU DO NOT AGREE TO THESE TERMS, YOU ARE NOT AUTHORIZED TO ACCESS, DOWNLOAD, USE OR REVIEW THE MATERIALS.
For good and valuable consideration, the receipt and sufficiency of which are acknowledged, You and Microsoft agree as follows: 1. You may review these Materials only (a) as a reference to assist You in planning and designing Your product, service or technology ("Product") to interface with a Microsoft product, specification, service or technology ("Microsoft Product") as described in these Materials; and (b) to provide feedback on these Materials to Microsoft. All other rights are retained by Microsoft; this Agreement does not give You rights under any Microsoft patents. You may not (i) duplicate any part of these Materials, (ii) remove this Agreement or any notices from these Materials, or (iii) give any part of these Materials, or assign or otherwise provide Your rights under this Agreement, to anyone else. 2. These Materials may contain preliminary information or inaccuracies, and may not correctly represent any associated Microsoft Product as commercially released. All Materials are provided entirely "AS IS." To the extent permitted by law, MICROSOFT MAKES NO WARRANTY OF ANY KIND, DISCLAIMS ALL EXPRESS, IMPLIED AND STATUTORY WARRANTIES, AND ASSUMES NO LIABILITY TO YOU FOR ANY DAMAGES OF ANY TYPE IN CONNECTION WITH THESE MATERIALS OR ANY INTELLECTUAL PROPERTY IN THEM. 3. If You are an entity and (a) merge into another entity or (b) a controlling ownership interest in You changes, Your right to use these Materials automatically terminates and You must destroy them. 4. You have no obligation to give Microsoft any suggestions, comments or other feedback ("Feedback") relating to these Materials. However, any Feedback you voluntarily provide may be used in Microsoft Products and related specifications or other documentation (collectively, "Microsoft Offerings") which in turn may be relied upon by other third parties to develop their own products, services or technology ("Third Party Products"). Accordingly, if You do give Microsoft Feedback on any version of these Materials or the Microsoft Offerings to which they apply, You agree: (a) Microsoft may freely use, reproduce, license, distribute, and otherwise commercialize Your Feedback in any Microsoft Offering; (b) You also grant third parties, without charge, only those patent rights necessary to enable Third Party Products to use, implement or interface with any specific parts of a Microsoft Product that incorporate Your Feedback; and (c) You will not give Microsoft any Feedback (i) that You have reason to believe is subject to any patent, copyright or other intellectual property claim or right of any third party; or (ii) subject to license terms which seek to require any Microsoft Offering incorporating or derived from such Feedback, or other Microsoft intellectual property, to be licensed to or otherwise shared with any third party. 5. Microsoft has no obligation to maintain the confidentiality of any Microsoft Offering, or the confidentiality of Your Feedback, including Your identity as the source of such Feedback. 6. This Agreement is governed by the laws of the State of Washington. Any dispute involving it must be brought in the federal or state superior courts located in King County, Washington, and You waive any defenses allowing the dispute to be litigated elsewhere. If there is litigation, the losing party must pay the other party's reasonable attorneys' fees, costs and other expenses. If any part of this Agreement is unenforceable, it will be considered modified to the extent necessary to make it enforceable, and the remainder shall continue in effect. This Agreement is the entire agreement between You and Microsoft concerning these Materials; it may be changed only by a written document signed by both You and Microsoft.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
Version 0.7
iii
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
v
Contents
Preface ............................................................................................................................xiii
PART I. T HE METRO FRAMEWORK ............................................................................ 1
Chapter 1. Overview of the Met ro Framework ................................................................3 1.1 Standards and Conformance .................................................................................... 3 1.1.1 XML 1.0 ................................................................................................................ 3 1.1.2 RFC 2396 .............................................................................................................. 3 1.1.3 RFC 2616 .............................................................................................................. 3 1.1.4 .ZIP File Format Specification .................................................................................. 3 1.1.5 X.509 ................................................................................................................... 3 1.1.6 XML-Signature Syntax and Processing ...................................................................... 3 1.1.7 RFC 2510 .............................................................................................................. 4 1.1.8 Date and Time Formats .......................................................................................... 4 1.1.9 XML Namespaces ................................................................................................... 4 1.1.10 JPEG .................................................................................................................... 4 1.1.11 PNG ..................................................................................................................... 4 1.1.12 TIFF ..................................................................................................................... 4 1.1.13 Unicode ................................................................................................................ 4 1.1.14 Unicode Character Database.................................................................................... 4 1.1.15 XML Base .............................................................................................................. 4 1.1.16 Print Schema ......................................................................................................... 4 1.1.16.1 Print Schema Keywords ................................................................................. 4 1.1.17 RFC 2234 .............................................................................................................. 4 1.1.18 OpenType Specification........................................................................................... 5 1.2 Implementation Notes ............................................................................................ 5
Chapter 2. The Package Model .......................................................................................7 2.1 Packages and Parts ................................................................................................ 7 2.1.1 Part Names ........................................................................................................... 7 2.1.1.1 Part Name Syntax ......................................................................................... 7 2.1.1.2 Equivalence of Part Names ............................................................................. 8 2.1.1.3 Creating a Normalized Unicode String from a Part Name .................................... 8 2.1.1.4 Rules for Part Naming .................................................................................... 9 2.1.2 Part URI Addressing ............................................................................................... 9 2.1.2.1 Relative URIs in Packages .............................................................................. 9 2.1.2.2 Fragments.................................................................................................. 10 2.1.3 Content Types ..................................................................................................... 10 2.1.4 Growth Hint ........................................................................................................ 10 2.1.5 Relationships ....................................................................................................... 11 2.1.5.1 Representing Relationships........................................................................... 11 2.1.5.2 Bidirectional Relationship Traversal ............................................................... 14 2.1.6 Package Relationships .......................................................................................... 14 Chapter 3. Physical Packages ...................................................................................... 15 3.1 Physical Model .................................................................................................... 15 3.1.2 Access Style ........................................................................................................ 15 3.1.2.1 Streaming Consumption ............................................................................... 15 3.1.2.2 Streaming Creation ..................................................................................... 15 3.1.2.3 Simultaneous Creation and Consumption ....................................................... 16 3.1.3 Layout Styles ...................................................................................................... 16 3.1.4 Communication Styles .......................................................................................... 17 3.2 Physical Mappings................................................................................................ 18 3.2.1 Components Being Mapped ................................................................................... 18 3.2.2 Common Mapping Patterns.................................................................................... 18 3.2.3 Identifying Content Types of Parts ......................................................................... 19 3.2.4 Interleaving ........................................................................................................ 21 3.3 Specific Mappings ................................................................................................ 21 3.3.1 Mapping to a ZIP Archive ...................................................................................... 22 3.3.1.2 Mapping Part Data....................................................................................... 22 3.3.1.3 Converting Part Names to ZIP Archive Item Names ......................................... 22 3.3.1.4 Converting ZIP Archive Item Names to Part Names ......................................... 22
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL vi
Contents
3.4
Metro Specification and Reference Guide
3.3.1.5 Limitations ..................................................................................................22 3.3.1.6 Mapping Part Content Type ...........................................................................23 3.3.1.7 Mapping the Growth Hint ..............................................................................23 3.3.1.8 ZIP Format Clarifications for Metro .................................................................23 Ensuring Interleaved ZIP Packages Are Well-Ordered .................................................24
Chapter 4. Versioning and Extensibility ....................................................................... 25 4.1 Summary............................................................................................................25 4.2 Versioning Namespace ..........................................................................................26 4.3 Backward and “Forward” Compatibility.....................................................................27 4.4 Versioning Markup................................................................................................27 4.4.2 The Compatibility Rule Attributes............................................................................28 4.4.2.1 The Ignorable Attribute ................................................................................28 4.4.2.2 The ProcessContent Attribute ........................................................................29 4.4.2.3 The PreserveElements and PreserveAttributes Attributes ..................................30 4.4.2.4 The MustUnderstand Attribute .......................................................................31 4.4.3 The Alternate Content Elements .............................................................................31 4.4.3.1 The Element .................................................................................32 4.4.3.2 The Requires Attribute..................................................................................32 4.4.3.3 The Element ...............................................................................32 4.4.4 Versioning Markup Examples..................................................................................33 4.4.4.1 Using the Ignorable Attribute ........................................................................33 4.4.4.2 Using the MustUnderstand Attribute ...............................................................33 4.4.4.3 Using AlternateContent.................................................................................34 Chapter 5. Package-Wide Features .............................................................................. 37 5.1 Core Properties....................................................................................................37 5.1.2 Discoverability of Core Properties ...........................................................................38 5.1.3 Versioning and Extensibility for Core Properties ........................................................38 5.2 Digital Signatures.................................................................................................38 5.2.2 Choosing Content to Sign ......................................................................................39 5.2.3 Metro Digital Signature Parts .................................................................................40 5.2.4 Signature Markup Example ....................................................................................40 5.2.5 The SignatureOrigin Part .......................................................................................42 5.2.6 The Signature Part................................................................................................42 5.2.6.2 The Element ...........................................................................43 5.2.6.3 The Metro-Specific Element ............................................................45 5.2.6.4 Application-Specific s......................................................................50 5.2.6.5 Summary of Metro Restrictions to the XML Digital Signature Specification...........50 5.2.7 The Certificate Part ...............................................................................................51 5.2.8 Generating Signatures ..........................................................................................51 5.2.8.1 Reference Generation ...................................................................................51 5.2.8.2 Signature Generation ...................................................................................52 5.2.9 Validating Signatures ............................................................................................52 5.2.9.1 Reference Validation ....................................................................................52 5.2.9.2 Signature Validation.....................................................................................52 5.2.10 Versioning and Extensibility Support .......................................................................53 5.2.10.1 Using Relationship Types ..............................................................................53 5.2.10.2 Versioning Namespace for Metro Digital Signatures ..........................................53 5.3 Thumbnail Parts in Metro Packages .........................................................................53
PART II. THE REACH PACKAGE F ORMAT ....................................................................55 Chapter 6. The Reach Package Format ......................................................................... 57 6.1 The Fixed Payload ................................................................................................58 6.1.2 Fixed Payload Relationships ...................................................................................60 6.1.3 The FixedDocumentSequence Part ..........................................................................61 6.1.4 The FixedDocument Part .......................................................................................61 6.1.5 The FixedPage Part ...............................................................................................62 6.1.6 Image Parts.........................................................................................................62 6.1.6.1 Supported Formats ......................................................................................62 6.1.7 Thumbnail Parts ...................................................................................................64 6.1.8 Font Parts............................................................................................................65 6.1.8.1 Subsetting Fonts..........................................................................................65 6.1.8.2 Reach OpenType Font Embedding ..................................................................65
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
Contents
vii
6.1.8.3 Embedded Font Obfuscation ......................................................................... 67 6.1.9 PrintTicket Parts .................................................................................................. 68 6.1.9.1 PrintTicket Defintion .................................................................................... 68 6.1.9.2 Mapping PrintTicket Parts to the Fixed Payload Parts........................................ 68 6.1.9.3 Processing PrintTicket Parts Within the Reach Package..................................... 68 6.1.10 Annotations Part .................................................................................................. 69 6.2 Specifying Content Structure ................................................................................. 70 6.2.1 Reading Order ..................................................................................................... 70 6.2.2 Hyperlinks........................................................................................................... 70 6.2.2.1 Hyperlink Activation..................................................................................... 70 6.2.2.2 Reach Package URI Fragments...................................................................... 71 6.2.3 Accessibility ........................................................................................................ 71 6.3 Validity Rules for Reach Packages........................................................................... 71 6.4 Interleaving Optimizations for Reach Packages ......................................................... 72 6.4.1 Optimizing Interleaving Order................................................................................ 72 6.4.2 Consuming Interleaved Packages ........................................................................... 74 6.4.3 Reach Consumers with Resource Constraints ........................................................... 74 6.4.3.1 The DiscardControl Part ............................................................................... 74
Chapter 7. Reach Markup Basics .................................................................................. 77 7.1 Reach and Other Markup Standards ........................................................................ 77 7.2 Reach Markup Model ............................................................................................ 77 7.2.1 Property Syntax................................................................................................... 78 7.2.2 Property Attribute Syntax...................................................................................... 78 7.2.3 Property Element Syntax ...................................................................................... 78 7.3 Language in Reach Packages ................................................................................. 79 7.4 Diagram Notes .................................................................................................... 80 7.5 Document Markup................................................................................................ 81 7.5.1 FixedDocumentSequence Element .......................................................................... 81 7.5.1.1 DocumentReference Element ........................................................................ 81 7.5.2 FixedDocument Element ....................................................................................... 82 7.5.2.1 PageContent Element .................................................................................. 83 7.5.2.2 PageContent.LinkTargets Element ................................................................. 84 7.5.2.3 LinkTarget Element ..................................................................................... 84 7.5.3 FixedPage Element ............................................................................................... 85 7.5.3.2 BleedBox Attribute ...................................................................................... 89 7.5.3.3 ContentBox Attribute ................................................................................... 90 7.6 Page Markup....................................................................................................... 91 7.6.1 Canvas Element ................................................................................................... 91 7.6.2 Path Element ....................................................................................................... 93 7.6.3 Glyphs Element ................................................................................................... 93 Chapter 8. Graphics..................................................................................................... 95 8.1 Path Element ...................................................................................................... 95 8.1.1 Path.Data Element ..............................................................................................100 8.1.2 FillRule Attributes................................................................................................101 8.1.3 Path.Fill Element .................................................................................................102 8.1.4 Path.Stroke Element............................................................................................103 8.2 Geometries and Figures ...................................................................................... 104 8.2.1 Geometries ........................................................................................................104 8.2.1.1 GeometryGroup .........................................................................................105 8.2.1.2 CombinedGeometry ....................................................................................107 8.2.1.3 PathGeometry............................................................................................111 8.2.2 Figures ..............................................................................................................113 8.2.2.1 PathFigure.................................................................................................113 8.2.2.2 StartSegment Element................................................................................114 8.2.2.3 Middle Segment – ArcSegment ....................................................................114 8.2.2.4 Middle Segment – BezierSegment ................................................................118 8.2.2.5 Middle Segment – LineSegment ...................................................................119 8.2.2.6 Middle Segment – PolyBezierSegment ..........................................................120 8.2.2.7 Middle Segment – PolyLineSegment .............................................................121 8.2.2.8 Middle Segment – PolyQuadraticBezierSegment .............................................122 8.2.2.9 Middle Segment – QuadraticBezierSegment...................................................123 8.2.2.10 CloseSegment............................................................................................125 8.2.3 Abbreviated Geometry Syntax ..............................................................................126
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL viii
Contents
Metro Specification and Reference Guide
Chapter 9. Text......................................................................................................... 131 9.1 Glyphs Element.................................................................................................. 131 9.1.1 Glyphs Metrics ................................................................................................... 135 9.1.2 Mapping Code Units to Glyphs.............................................................................. 136 9.1.2.1 One-to-One Mappings ................................................................................ 137 9.1.2.2 Many-to-One Mappings............................................................................... 137 9.1.2.3 One-to-Many Mappings............................................................................... 137 9.1.2.4 Many-to-Many Mappings............................................................................. 138 9.1.3 Using the Indices Attribute to Specify Glyph Runs................................................... 139 9.1.3.2 Specifying Character-to-Glyph Mappings....................................................... 140 9.1.4 Using the UnicodeString Attribute ......................................................................... 140 9.1.5 Using the StyleSimulations Attribute ..................................................................... 141 9.1.6 Using the CaretStops Attribute to Specify Caret Placement ...................................... 141 9.1.7 Glyphs.Fill ......................................................................................................... 142 9.1.8 Sideways Text.................................................................................................... 142 9.1.8.1 Sideways Text Origin Calculation ................................................................. 142 9.1.9 Device Fonts ...................................................................................................... 143 9.1.10 Specifying the Glyph Language ............................................................................ 143 9.1.11 Glyphs Markup Examples..................................................................................... 144 9.1.12 Optimizing the Size of Glyphs Markup ................................................................... 145 9.1.12.1 Optimizing Markup of Glyph Indices ............................................................. 145 9.1.12.2 Optimizing Markup of Glyph Positions ........................................................... 146 Chapter 10. Brushes ................................................................................................... 147 10.2 SolidColorBrush ................................................................................................. 148 10.3 ImageBrush ...................................................................................................... 149 10.4 VisualBrush ....................................................................................................... 153 10.4.1 VisualBrush.Visual .............................................................................................. 155 10.5 Common Attributes for ImageBrush and VisualBrush................................................ 157 10.5.1 Rendering Images and Visuals ............................................................................. 157 10.5.2 Image Example .................................................................................................. 157 10.5.3 Viewbox and Viewport Examples .......................................................................... 158 10.5.4 Stretch.............................................................................................................. 160 10.5.5 TileMode ........................................................................................................... 160 10.5.5.2 TileMode Tile ............................................................................................. 163 10.5.5.3 TileMode FlipX ........................................................................................... 165 10.5.5.4 TileMode FlipY ........................................................................................... 168 10.5.5.5 TileMode FlipXY ......................................................................................... 170 10.6 GradientBrushes ................................................................................................ 173 10.6.1 LinearGradientBrush ........................................................................................... 173 10.6.1.2 LinearGradientBrush.GradientStops.............................................................. 176 10.6.1.3 LinearGradientBrush SpreadMethod Examples ............................................... 176 10.6.2 RadialGradientBrush ........................................................................................... 180 10.6.2.2 RadialGradientBrush.GradientStops.............................................................. 183 10.6.2.3 RadialGradientBrush SpreadMethod Examples ............................................... 184 10.6.3 GradientStop ..................................................................................................... 188 10.7 Using a Brush as an OpacityMask .......................................................................... 189 Chapter 11. Shared Element Attributes........................................................................ 191 11.2 Opacity Attribute................................................................................................ 192 11.3 Hyperlink Attributes............................................................................................ 192 11.3.1 Name Attribute .................................................................................................. 192 11.3.2 FixedPage.NavigateUri Attribute ........................................................................... 193 11.4 Resource and Resource References ....................................................................... 194 11.4.2 Defining Fixed Payload Resource Dictionaries ......................................................... 196 11.4.3 Referencing Resources ........................................................................................ 197 11.4.4 Scoping Rules for Resolving Resource References ................................................... 197 11.5 Clipping............................................................................................................ 198 11.5.1 Canvas.Clip ....................................................................................................... 199 11.5.2 Path.Clip ........................................................................................................... 200 11.5.3 Glyphs.Clip ........................................................................................................ 201 11.6 Positioning Content ............................................................................................ 203 11.6.1 MatrixTransform................................................................................................. 203 11.6.2 FixedPage.RenderTransform ................................................................................ 206 11.6.3 Canvas.RenderTransform .................................................................................... 206
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
Contents
ix
11.6.4 Path.RenderTransform .........................................................................................207 11.6.5 Glyphs.RenderTransform......................................................................................208 11.6.6 GeometryGroup.Transform...................................................................................209 11.6.7 CombinedGeometry.Transform .............................................................................211 11.6.8 PathGeometry.Transform .....................................................................................212 11.6.9 ImageBrush.Transform ........................................................................................213 11.6.10 VisualBrush.Transform.........................................................................................214 11.6.11 LinearGradientBrush.Transform ............................................................................215 11.6.12 RadialGradientBrush.Transform ............................................................................216 11.7 OpacityMask ..................................................................................................... 217 11.7.1 Canvas.OpacityMask............................................................................................217 11.7.2 Path.OpacityMask ...............................................................................................219 11.7.3 Glyphs.OpacityMask ............................................................................................220
Chapter 12.1 12.2 12.3 12.4
12. Color ........................................................................................................ 223 Color Support in Reach Documents ....................................................................... 223 Advanced Color Extensions.................................................................................. 223 Raster Image Color Extensions ............................................................................ 223 Alpha Blending and Gradient Blending ................................................................... 223
Chapter 13. Rendering Rules ....................................................................................... 225 13.1 Rendering Details for Reach Markup...................................................................... 225 13.1.1 Coordinate Systems and Units ..............................................................................225 13.1.1.1 Page Dimensions........................................................................................225 13.1.2 Implementation Limits .........................................................................................225 13.1.3 Transforms.........................................................................................................227 13.1.4 Rounding of Coordinates ......................................................................................227 13.1.5 Pixel Center Location/Pixel Placement/Pixel Inclusion ..............................................228 13.1.6 Maximum Placement Error ...................................................................................228 13.1.7 Abutment of Shapes............................................................................................228 13.1.8 Clipping Behavior ................................................................................................228 13.1.9 Computation of Gradients ....................................................................................229 13.1.9.1 Linear Gradients.........................................................................................229 13.1.9.2 Radial Gradients.........................................................................................231 13.1.10 Opacity Computations .........................................................................................233 13.1.11 Composition Rules...............................................................................................235 13.1.11.1 Composition Examples ................................................................................237 13.1.12 Stroke Edge Parallelization ...................................................................................240 13.1.13 Pixel Placement for Glyphs ...................................................................................241 13.1.14 Rules for Dash Cap Rendering ..............................................................................241 13.1.15 Binary Combination of Geometries () ....................................244 13.1.16 Rules for Line Cap Rendering................................................................................245 13.1.17 Rules for Degenerate Line and Curve Segments ......................................................247
PART III. SCHEMA R EFERENCE ............................................................................ 249 Chapter 14. Markup Reference..................................................................................... 251 14.1 Document Markup.............................................................................................. 251 14.1.1 FixedDocumentSequence .....................................................................................251 14.1.2 DocumentReference ............................................................................................251 14.1.3 FixedDocument ...................................................................................................252 14.1.4 PageContent.......................................................................................................252 14.1.5 PageContent.LinkTargets .....................................................................................253 14.1.6 LinkTarget..........................................................................................................253 14.2 Page Markup..................................................................................................... 254 14.2.1 FixedPage ..........................................................................................................254 14.2.1.1 FixedPage.RenderTransform ........................................................................255 14.2.1.2 FixedPage.Resources ..................................................................................256 14.2.2 Canvas ..............................................................................................................256 14.2.2.1 Canvas.RenderTransform ............................................................................258 14.2.2.2 Canvas.Clip ...............................................................................................258 14.2.2.3 Canvas.OpacityMask ...................................................................................259 14.2.2.4 GeometryGroup.Transform ..........................................................................259 14.2.2.5 CombinedGeometry.Transform ....................................................................259 14.2.2.6 PathGeometry.Transform ............................................................................260
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL x
Contents
Metro Specification and Reference Guide
14.2.2.7 ImageBrush.Transform............................................................................... 260 14.2.2.8 VisualBrush.Transform ............................................................................... 260 14.2.2.9 LinearGradientBrush.Transform ................................................................... 261 14.2.2.10 RadialGradientBrush.Transform ................................................................... 261 14.2.2.11 Canvas.Resources...................................................................................... 261 14.2.3 ResourceDictionary ............................................................................................. 262 14.2.4 MatrixTransform................................................................................................. 263 14.3 Graphics Markup ................................................................................................ 264 14.3.1 Path.................................................................................................................. 264 14.3.1.1 Path.Data ................................................................................................. 268 14.3.1.2 Path.RenderTransform................................................................................ 269 14.3.1.3 Path.Clip................................................................................................... 269 14.3.1.4 Path.OpacityMask ...................................................................................... 269 14.3.1.5 Path.Fill .................................................................................................... 270 14.3.1.6 Path.Stroke............................................................................................... 270 14.3.2 Geometry .......................................................................................................... 271 14.3.2.1 GeometryGroup......................................................................................... 271 14.3.2.2 GeometryGroup.Transform ......................................................................... 272 14.3.2.3 CombinedGeometry ................................................................................... 272 14.3.2.4 CombinedGeometry.Geometry1 ................................................................... 273 14.3.2.5 CombinedGeometry.Geometry2 ................................................................... 273 14.3.2.6 CombinedGeometry.Transform .................................................................... 274 14.3.2.7 PathGeometry.Transform............................................................................ 274 14.3.3 Figures.............................................................................................................. 275 14.3.3.1 PathFigure ................................................................................................ 275 14.3.3.2 StartSegment............................................................................................ 275 14.3.3.3 ArcSegment .............................................................................................. 276 14.3.3.4 BezierSegment .......................................................................................... 277 14.3.3.5 LineSegment ............................................................................................. 277 14.3.3.6 PolyBezierSegment .................................................................................... 278 14.3.3.7 PolyLineSegment ....................................................................................... 279 14.3.3.8 PolyQuadraticBezierSegment....................................................................... 279 14.3.3.9 QuadraticBezierSegment ............................................................................ 280 14.4 Brushes Markup ................................................................................................. 281 14.4.1 SolidColorBrush.................................................................................................. 281 14.4.2 ImageBrush ....................................................................................................... 282 14.4.2.1 ImageBrush.Transform............................................................................... 284 14.4.3 VisualBrush ....................................................................................................... 284 14.4.3.1 VisualBrush.Transform ............................................................................... 286 14.4.3.2 VisualBrush.Visual ..................................................................................... 287 14.4.4 LinearGradientBrush ........................................................................................... 287 14.4.4.1 LinearGradientBrush.GradientStops.............................................................. 289 14.4.5 RadialGradientBrush ........................................................................................... 290 14.4.5.1 RadialGradientBrush.GradientStops.............................................................. 292 14.4.6 GradientStop ..................................................................................................... 293 14.5 Text Markup ...................................................................................................... 294 14.5.1 Glyphs .............................................................................................................. 294 14.5.1.1 Glyphs.RenderTransform ............................................................................ 298 14.5.1.2 Glyphs.Clip ............................................................................................... 298 14.5.1.3 Glyphs.OpacityMask ................................................................................... 299 14.5.1.4 Glyphs.Fill................................................................................................. 299
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
Contents
xi
PART IV. APPENDICES ...................................................................................... 301
Appendix A. Glossary of Terms ..................................................................................... 303
Appendix B. Converting Unicode Strings to Part Names ................................................ 307 B.2 Creating an ASCII String [2] from a Unicode String [arc 1-2] ................................... 307 B.3 Creating a Part Name [3] from an ASCII String [arc 2-3] ......................................... 307 B.4 String Conversion Examples ................................................................................ 308 Appendix C. The Pack URI............................................................................................ 309 C.1 The Pack URI Scheme ........................................................................................ 309 C.2 Resolving a Pack URI to a Resource ...................................................................... 310 C.3 Composing a Pack URI........................................................................................ 311 C.4 Normalization and Equivalence............................................................................. 311 Appendix D. ZIP Appnote.txt Clarifications ................................................................... 313 Appendix E.
Relationships Schema............................................................................... 325
Appendix F.
Core Properties Schema ............................................................................ 327
Appendix G. Metro Schema .......................................................................................... 329 Appendix H. Standard Namespaces and Content Types.................................................. 345 H.1 XML Namespace URIs ......................................................................................... 345 H.1.1 Package-Wide Namespaces ..................................................................................345 H.1.2 Reach-Specific Namespaces .................................................................................345 H.2 Content Types................................................................................................... 346 H.2.1 Package-Wide Content Types................................................................................346 H.2.2 Reach-Specific Content Types...............................................................................346 H.3 Relationship Types............................................................................................. 347 H.3.1 Package-Wide Relationship Types .........................................................................347 H.3.2 Reach-Specific Relationship Types.........................................................................347
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
xiii
Preface
About This Specification
Metro is the codename for the set of conventions for the use of XML and other widely available
technologies to describe the content and appearance of paginated documents.
Part I, “The Metro Framework" describes packaging and physical format conventions for the use of XML, Unicode, ZIP and other widely available technologies and specifications to organize the content and resources that make up any document. Although an integral part of the Metro specification, the packaging conventions described in Part I are flexible enough to organize and store any content. Part II, “The Reach Package Format” presents the primarily XML-based format for paginated documents: the Reach package . This section describes the XML markup that defines the composition of the document and the visual appearance of each page. Part II also provides rendering rules to display or print a Reach package with full fidelity by devices and applications within a wide range of environments and scenarios. This specification is written for developers who are building systems that process Metro content. A primary goal of the Metro specification is to ensure the interoperability of independently created software and hardware systems reading or writing Metro content. This specification defines the formal requirements that systems that read or write Metro content must satisfy in order to achieve this interoperability. The information contained in this specification is subject to change. Every effort has been made to ensure accuracy at the time of publication.
Formatting Conventions This specification uses the following formatting conventions: Terms are formatted like this.
Code looks like this. Raw text and editorial notes look like this.
Language Notes In this specification, the words that are used to define the significance of each particular requirement are capitalized. These words are used in accordance with their definitions in RFC 2119 and their meaning is reproduced here for convenience: •
MUST. This word, or the adjective “REQUIRED,” means that the item is an absolute requirement of the specification.
•
SHOULD. This word, or the adjective “RECOMMENDED,” means that there may exist valid reasons in particular circumstances to ignore this item, but the full implications should be understood and the case carefully weighed before choosing a different course.
•
MAY. This word, or the adjective “OPTIONAL,” means that this item is truly optional. For example, one implementation may choose to include the item because a particular marketplace or scenario requires it or because it enhances the product. Another implementation may omit the same item.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
1
Part I. T H E M ET R O F R A M EW OR K
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
3
Chapter 1. Overview of the Metro Framework
The structure and functionality of the Metro package framework are represented by a packaging model and a physical model .
The packaging model defines a package abstraction that holds a collection of parts . The parts are composed, processed, and persisted according to a set of rules. Parts have relationships to each other, as well as to the package itself. The Metro packaging model specifies the way parts of a document are named and related. Parts of Metro packages have content types and are unambiguously addressed using the well-defined naming guidelines. The physical model defines the mapping between the components of the packaging model to the features of a particular physical format. That format is based on the ZIP specification. Because the Metro specification will continue to evolve, Metro packages are designed to accommodate extensions and to support compatibility goals. The versioning semantics and mechanisms support compatibility between software systems based on different versions of the Metro specification while allowing package creators to exploit new or proprietary features. For more information, see Chapter 4, “Versioning and Extensibility”.
1.1
Standards and Conformance
1.1.1 XML 1.0 The W3C Recommendation Extensible Markup Language (XML) 1.0 (Third Edition) is located at http://www.w3.org/TR/REC-xml.
1.1.2 RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax. The Internet Society, 1998.
1.1.3 RFC 2616 Hypertext Transfer Protocol – HTTP/1.1. The Internet Society, 1999.
1.1.4 .ZIP File Format Specification .ZIP File Format Specification (Version 6.2.1) is published by PKWARE, Inc. at http://www.pkware.com/company/standards/appnote/.
1.1.5 X.509 ITU-T Recommendation X.509 version 3 (1997). Information Technology — Open Systems Interconnection — The Directory Authentication Framework ISO/IEC 9594-8:1997.
1.1.6 XML-Signature Syntax and Processing The W3C Recommendation XML-Signature Syntax and Processing is located at http://www.w3.org/TR/xmldsig-core/.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 4
1.1 Standards and Conformance
Metro Specification and Reference Guide
1.1.7 RFC 2510
Internet X.509 Public Key Infrastructure Certificate Management Protocols. The Internet Society, 1999.
1.1.8 Date and Time Formats
The W3C Note Date and Time Formats is located at http://www.w3.org/TR/NOTE-datetime.
1.1.9 XML Namespaces The W3C Recommendation Namespaces in XML 1.1 is located at http://www.w3c.org/TR/xml-names11.
1.1.10 JPEG JPEG File Interchange Format, Version 1.02 (ISO DIS 10918-1, JPEG JFIF). The specification is located at http://www.w3.org/Graphics/JPEG/jfif.txt.
1.1.11 PNG Portable Network Graphics (PNG): Functional specification. ISO/IEC 15948:2003 (E). The specification is located at http://www.w3.org/TR/2003/REC-PNG-20031110.
1.1.12 TIFF TIFF image parts MUST contain images using the specification located at partners.adobe.com/public/developer/en/tiff/TIFF6.pdf.
1.1.13 Unicode The Unicode Consortium. The Unicode Standard, Version 4.0.0, defined by: The Unicode Standard, Version 4.0 (Boston, MA, Addison-Wesley, 2003. ISBN 0-321-18578-1).
1.1.14 Unicode Character Database The Unicode Character Database is located at http://www.unicode.org/Public/4.0-Update/UCD-4.0.0.html.
1.1.15 XML Base The W3C Recommendation XML Base is located at http://www.w3.org/TR/xmlbase/.
1.1.16 Print Schema http://winfx.msdn.microsoft.com/library/default.asp?url=/library/enus/printschema/PrintSchema/Overviews/PrintSchema_background.asp 1.1.16.1
Print Schema Keywords
http://winfx.msdn.microsoft.com/library/default.asp?url=/library/enus/printschema/PrintSchema/Keyword_entry.asp
1.1.17 RFC 2234 Augmented BNF for Syntax Specifications: ABNF. The Internet Society. 1997.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
1.2 Implementation Notes
5
1.1.18 OpenType Specification
http://www.microsoft.com/typography/otspec/default.htm
1.2
Implementation Notes
Implementation details are provided in many sections throughout this specification. This specification is intended to describe the planned design for implementation in the Microsoft Windows operating system code-named “Longhorn” and in the Windows API Pack. However, the current implementation of the Metro specification in Longhorn and the Windows API Pack does not generate the markup documented in the following sections: •
Chapter 4, “Versioning and Extensibility”
•
Section 6.1.6.1, “Supported Formats” on page 62 (color profiles are currently ignored)
•
Section 6.1.8.2, “Reach OpenType Font Embedding” on page 65
•
Section 9.1.9, “Device Fonts” on page 143
The namespaces used in examples are subject to change.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
7
Chapter 2. The Package Model 2.1
Packages and Parts
In Metro, content is held within a package. A package is a logical entity that holds a collection of parts. The purpose of the package is to aggregate all of the pieces of a document (or other types of content) into one object that is easy for developers and end-users to deal with. For example, a package holding a document with a picture might contain two parts: an XML markup part representing the document and another part representing the picture. A part is a stream of bytes with associated common properties (e.g., name). This is analogous to a file in a file system or to a resource on an HTTP server. In addition to content, each part has the following common properties: •
Name — the name of the part [REQUIRED]
•
Content Type — the type of content stored in the part [REQUIRED]
•
Growth Hint — a suggested number of bytes to reserve for the part to grow in-place [OPTIONAL]
The package provides a convenient way to distribute documents with all of their component pieces, such as images, fonts, and data. Although this specification defines a single-file package format, the package model allows for the future definition of other physical package representations. For example, a package could be physically represented in a collection of loose files, in a database, or ephemerally in transit over a network connection. Within a package, parts MAY be physically compressed or interleaved. The package is capable of storing relationships between parts. The package is also capable of holding digital signatures applied to parts. Additionally, this specification defines a URI scheme, the pack URI scheme , that allows URIs to be used as a uniform mechanism for addressing parts inside a package.
2.1.1
Part Names
Parts have part names. Like in file systems or in the world of URIs, part names are hierarchical. Part names are divided into segments, each representing a level in the hierarchy. For example, the part name “/hello/world/doc.xml” contains three segments: “hello”, “world”, and “doc.xml”. Segments can be seen to form a tree. This is similar to file systems, where all of the non-leaf nodes in the tree are folders and the leaf nodes are files which contain actual content. The “folder” nodes (i.e., non-leaf nodes) in the name tree serve a similar function of organizing the parts in the package. Note that folder-like nodes exist only as a concept in the naming hierarchy. Folders are not explicitly represented in the packaging model, and no directory of folders exists in the packaging model. However, physical representations MAY have an explicit representation of folders, and this representation MAY be in the form of a hierarchical directory. 2.1.1.1
Part Name Syntax
A part name is used to refer to a part in a package. Part names consist of ASCII characters. The grammar for part names is defined using the following rules, in ABNF (for more information, see Section 1.1.17, “RFC 2234” on page 4):
part_name = segment =
"/" segment *( "/" segment ) 1*pchar
pchar is defined in RFC 2396. For more information, see Section 1.1.2, “RFC 2396” on page 3.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 8
2.1 Packages and Parts
Metro Specification and Reference Guide
Part names have the following constraints: •
MAY contain escape-encoded triplets
•
MUST start with a forward slash (“/”)
•
MUST NOT have complete segments equal to “.”, “..” or any number of dots
•
MUST NOT have any segments which are empty
•
MUST NOT contain excluded ASCII characters (see RFC 2396 section 2.4.3) and question mark. Note that excluded ASCII characters MAY be present in escape-encoded form unless they are explicitly restricted as follows: •
MUST NOT contain the following characters: “.”, “/”, “\” in an escaped form
•
MUST NOT have escaped unreserved characters
Example
/a/%D1%86.xml 2.1.1.2
Equivalence of Part Names
Within a package, equivalent part names are not allowed. When comparing part names to determine equivalence, special care must be taken to correctly process the full range of Unicode characters, which can be represented in a part name by escape-encoded triplets. When testing part names for equivalency, the names must first be converted to normalized Unicode strings. Part names are considered equivalent if their normalized Unicode strings are byte-for-byte identical. 2.1.1.3
Creating a Normalized Unicode String from a Part Name
•
Convert a part name to a Unicode string, un-escape escaped UTF-8 octet sequences (excluding representing reserved ASCII characters) to Unicode code points as described in Section 3 of RFC 3629.
•
Convert the Unicode string to uppercase using simple case conversion as defined in the Unicode 3.1 standard, Section 3.13, “Default Case Operations.”
•
Perform normalization to NFC (Normal Form “C”) according to methods defined in the Unicode 4.0 standard, Sections 4.2 “Case-Normative” and 5.18 “Case Mappings.”
For example, the following part names are equivalent after normalization: Table 2–1. Part Name
Normalized Unicode String
/a/b.xml
/A/B.XML
/a/%D1%86.xml
/A/Ц.XML
/A/a.xml
/A/A.XML
/%25.xml
/%25.XML
/%2541.xml
/%2541.XML
/a.xml
/A.XML
/A.xml
/A.XML
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
2.1.1.4
2.1 Packages and Parts
9
Rules for Part Naming
The package and part naming model is flexible, allowing for a wide range of applications of the Metro package. However, it is important to recognize that Metro is designed to enable scenarios in which multiple, unrelated software systems can manipulate “their own” parts of a package without colliding with each other. To allow this, all writers and readers MUST adhere to the following part naming rules: •
The part name MUST NOT be derived from another part name by appending segments to it. For example, if a package contains a part named
/segment1/segment2/.../segmentn Then any part in that package MUST NOT have any of the following names:
/segment1 /segment1/segment2 /segment1/segment2/.../segmentn-1 •
It is REQUIRED that writers adding parts into an existing container do so in a new “folder” of the naming hierarchy, rather than placing parts directly in the root or in a pre-existing folder (unless the writer created that folder). In this way, the possibility of name conflicts is limited to the first segment of the part name. Parts created within this new folder can be named without risking conflicts with existing parts.
•
In the event that the preferred name for the folder is already used by an existing part, a writer MUST adopt some strategy for choosing alternate folder names. Writers MAY use the strategy of appending digits to the preferred name until an available folder name is found (possibly resorting to a GUID after some number of unsuccessful iterations).
•
One consequence of this policy is that readers MUST NOT attempt to locate a part via a “magic” or “well-known” part name. Instead, writers MUST create a package relationship to at least one part in each folder they create. Readers MUST use these package relationships to locate the parts rather than relying on well-known names.
•
Once a reader has found at least one part in a folder (via one of the package relationships mentioned above) it MAY use conventions about well-known part names to find other parts in that folder or its subfolders.
2.1.2 2.1.2.1
Part URI Addressing Relative URIs in Packages
Parts often contain references to other parts. For example, imagine a package with two parts: a markup file and an image. The markup file holds a reference to the image so that when the markup file is processed, the associated image can be identified and located. A relative URI in a Metro package is a reference to a part described such that the address of the referenced part is determined relative to the part containing the reference. Relative references from a part are interpreted relative to the base URI of that part. The terms base URI and relative URI are used in accordance with the URI specification (see RFC 2396). By default, the base URI of a part is derived from the name of the part, as it is defined in Section C.3, “Composing a Pack URI” on page 311. For example, a package may include parts with the following names:
/markup/page.xml /images/picture.jpg /images/other_picture.jpg If the “/markup/page.xml” part contains a URI reference to ”../images/picture.jpg”, then this relative reference MUST be interpreted as referring to the part name “/images/picture.jpg”.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 10
2.1 Packages and Parts
Metro Specification and Reference Guide
Parts MAY contain Unicode strings representing references to other parts. In particular, XML markup may contain such Unicode strings as a values of xsd:anyURI data type. These Unicode strings MUST be converted to ASCII strings, as defined in Section B.2, “Creating an ASCII String [2] from a Unicode String [arc 1-2]” on page 307, before resolving them relative to the base URI of the part containing the Unicode string.
Some types of content provide a way to override the default base URI by specifying a different base in the content, for example, XML Base (www.w3.org/TR/xmlbase/) or HTML (www.w3.org/TR/html401). In the presence of one of these overrides, the explicitly specified base URI MUST be used instead of the default.
2.1.2.2
Fragments
Sometimes it is useful to address a portion or specific point in a part. In the URI world, a fragment identifier is used [see RFC 2396.] In a container, the mechanism works the same way. Specifically, the fragment is a string that contains additional information that is understood in the context of the content type of the addressed part. For example, in a video file a fragment might identify a frame, in an XML file it might identify a portion of the XML file using an XPath expression. A fragment identifier is used in conjunction with a URI that addresses a part to identify fragments of the addressed part. The fragment identifier is optional and is separated from the URI by a crosshatch (“#”) character. As such, it is not part of a URI, but is often used in conjunction with a URI.
2.1.3
Content Types
Every part has a content type. This content type identifies what type of content is stored in a part. Examples of content types include “image/jpeg” and “application/xml”. For more information, see Section H.2, “Content Types” on page 346. The attribute syntax for the content types of Metro parts fits the definition for content types for Hypertext Transfer Protocol (RFC 2616, section 3.7), i.e., content types are well-structured ASCII strings with limited sets of characters. Content types MAY include comments, which have no semantic content and SHOULD be ignored during processing.
2.1.4
Growth Hint
In some scenarios, a part may be modified after it is placed into a package. Depending on the nature of the modification, the part might need to grow. For some physical package formats, this could be an expensive operation and could damage an otherwise well efficiently interleaved package. Ideally, it would be possible to enlarge the part in-place, without having to move around many of the bytes in the package. To support these scenarios efficiently, a growth hint MAY be associated with each part. This hint identifies the number of bytes by which the creator of the part imagines that the part will want to grow, while maintaining the efficiencies of in-place updating. In the physical mapping to a particular physical package format, this information MAY be used to reserve space to allow the part to grow. This number serves as a hint only, and physical mappings MAY choose to provide no such reserved space or to adhere only loosely to the hint. The growth hint is set when a part is created and cannot be changed after a part has been created.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
2.1.5
2.1 Packages and Parts
11
Relationships
Parts often contain references to other parts in a package and to resources outside of the package. In general, however, these references are represented inside the referring part in ways that are specific to the content type of the part, i.e., in arbitrary markup or an application-specific encoding. This effectively hides the internal and external linkages between parts from readers that do not understand the content types of the parts containing such references.
Even for common content types (such as the fixed payload markup described in Chapter 7, “Reach Markup Basics”), a Metro reader would need to parse all of the content in a part to discover and resolve the references to other parts. Metro introduces a higher-level mechanism to describe references from parts to other internal or external resources: relationships . Relationships provide a way to represent the kind of connection between a source part and a target resource. Relationships make the connections directly discoverable without looking at the content in the parts, so they are independent of content-specific schema and faster to resolve. Relationships provide a second important function: relating parts without modifying them. Sometimes this information serves as a form of annotation where the content type of the annotated part does not define a way to attach the given information. Finally, some scenarios require information to be attached to an existing part specifically without modifying that part, either because the part is encrypted and cannot be decrypted, or because it is digitally signed and changing it would invalidate the signature. 2.1.5.1
Representing Relationships
Relationships are represented in XML in a Relationships part . Each part in the container that is the source of one or more relationships has an associated Relationships part. This part holds the list of relationships for the source part. For more information, see Section H.2, “Content Types” on page 346. Figure 2–1 shows a FixedDocument part (called “Document1”) that binds together three pages. The set of pages bound together by the FixedDocument has a PrintTicket part associated with it, the “Primary Print Ticket”. Additionally, Page 2 has its own PrintTicket, the “Secondary Print Ticket”. The connections from the FixedDocument to its PrintTicket and from Page 2 to its PrintTicket are represented using relationships. The pages themselves are not related via relationships.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 12
2.1 Packages and Parts
Metro Specification and Reference Guide
Figure 2–1.
Document 1
Primary Print Ticket
/content/document1.xml
/tickets/ticket1.xml
Page 1
Page 2
Page 3
/content/p1.xml
/content/p2.xml
/content/p3.xml
Secondary Print Ticket /tickets/ticket2.xml
Add two rels parts to the diagram: /content/_rels/spine.xml.rels AND content/_rels/p2.xml.rels In Figure 2–1, the Relationships part for the FixedDocument is stored in “/content/_rels/document1.xml.rels” and the Relationships part for Page 2 is stored in “/content/_rels/p2.xml.rels”. Note the special naming convention in use here. First, the Relationships part for some (other) part in a given “folder” in the name hierarchy is stored in a “sub-folder” called “_rels”. Second, the name of the Relationships part is formed by appending “.rels” to the name of the original part. In Figure 2–1, the Relationships part associated with the FixedDocument contains a relationship that connects the Document1 part to ticket1.xml. This relationship is expressed as follows:
Relationships may also target resources outside of the package at some absolute location and resources located relative to the current location of a package entity. The following Relationships part specifies relationships that connect a part to pic1.jpg at an external absolute location, and to my_house.jpg at an external location relative to the location of the package:
Element
Some signed Metro parts may hold XML documents. Since XML allows equivalent content to be represented differently, a Canonicalization transform SHOULD be applied to the element prior to generating or validating a digital signature based on the content. Performing a Canonicalization transform ensures that can be validated even if the content has been regenerated using, for example, different entity structures, attribute ordering, or character encoding. The Metro infrastructure supports the following Canonicalization transforms: Canonical XML without comments (see http://www.w3.org/TR/2001/REC-xml-c14n-20010315) and Canonical XML with comments (see http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments).
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 44
5.2 Digital Signatures
Metro Specification and Reference Guide
. ... ...
Canonicalization transforms are RECOMMENDED also for s to parts that hold XML documents. These transforms are defined using the element.
... ...
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
5.2.6.3
5.2 Digital Signatures
45
The Metro-Specific Element
The element, a part of the XML digital signature namespace, is an immediate child of the element. The element is applied in the Metro framework with a specific structure and set of requirements. The Metro-specific MUST be uniquely identified using the Id attribute value of “Metro”. The Metro-specific MUST occur only once within an XML Signature
part. For a signed Metro package, Metro consumers MUST treat the absence of a Metro-specific , or the appearance of multiple Metro-specific s, as invalid signatures. Table 5–5. Metro-Specific Object
Namespace
Description
http://www.w3.org/2000/09/ xmldsig#
MUST have the string value “Metro”.
Attribute
Id
The Metro-specific holds as the immediate child element. The element holds and as immediate child elements. Table 5–6. Namespace
Description
Metro-Specific Child
http://www.w3.org/2000/09/ xmldsig#
Contains references to the signed parts of the package
http://www.w3.org/2000/09/ xmldsig#
Contains Metro Digital Signature timestamp
http://schemas.microsoft.com/metro /2005/02/digsig
Contains and elements
Elements
... ... ... ... 5.2.6.3.2
The Element
The element is a REQUIRED immediate child of the Metro-specific element. The element contains elements that can be used to specify additional information about the generation of a signature. The element MUST be used in Metro packages for containing the immediate child element that holds the date/time stamp for the signature. The element is part of the Metro Digital Signature namespace.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 46
5.2 Digital Signatures
Metro Specification and Reference Guide
... YYYY-MM-DDThh:mmTZD 2003-07-16T19:20+01:00
The element REQUIRES the immediate child element, which holds the format definition for the date/time stamp value stored in the element. The date/time format definition adheres to the syntax in the W3C Date and Time Formats note at http://www.w3.org/TR/NOTEdatetime. The components shown below MUST be present using the punctuation specified. Table 5–7. Abbreviations. YYYY
four-digit year
MM
two-digit month (01=January)
DD
two-digit day of month (01 through 31)
hh
two digits of hour (00 through 23) (am/pm NOT allowed)
mm
two digits of minute (00 through 59)
ss
two digits of second (00 through 59)
s
one or more digits representing a decimal fraction of a second
TZD
time zone designator (Z or +hh:mm or -hh:mm)
Table 1. Time/Date Format
Description
Example
YYYY
Year
1997
YYYY-MM
Year and month
1997-07
YYYY-MM-DD
Complete date
1997-07-16
YYYY-MMDDThh:mmTZD
Complete date plus hours and minutes
1997-07-16T19:20+01:00
YYYY-MMDDThh:mm:ssTZD
Complete date plus hours, minutes and seconds
1997-0716T19:20:30+01:00
YYYY-MMDDThh:mm:ss.sTZD
Complete date plus hours, minutes, seconds, and a decimal fraction of a second
1997-0716T19:20:30.45+01:00
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
5.2.6.3.3
5.2 Digital Signatures
47
The Element
The element contains references to the parts of the Metro package that are signed. The element MUST be used within the Metro-specific . The element MUST NOT contain references to any data not in the package. Table 5–8.
Namespace
Description
http://www.w3.org/2000/09/xmldsig#
Specifies a digest algorithm and a digest value, and (optionally) an identifier of the object being signed, the type of the object, and/or a list of transforms to be applied prior to digesting
Child Element
5.2.6.3.4
The Element
The element, part of the XML digital signature namespace, specifies a digest algorithm, digest value, the content type of the and a list of transforms to be applied prior to hashing. The element MUST occur at least once, and MAY occur more than once, as an immediate child element of the and/or elements. Table 5–9. Namespace
Description
Child
http://www.w3.org/2000/09/xmldsig#
A required element that identifies the digest algorithm to be applied to the signed object
http://www.w3.org/2000/09/xmldsig#
Contains the encoded value of the digest
http://www.w3.org/2000/09/xmldsig#
Elements
An optional element that contains an ordered list of elements which describe how the signer obtained the data object that was digested
For Metro packages, elements used within MUST refer only to local elements, using fragment identifiers. This Metro-specific requirement is more restrictive than the W3C Recommendation.
... ...
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 48
5.2 Digital Signatures
Metro Specification and Reference Guide
elements used within elements MUST refer only to parts of the same Metro package. The URI attribute of the elements MUST contain only relative URIs and MUST
NOT contain fragment identifiers.
One important feature of the references to package parts is the inclusion of part content type as a query component of the part URI. The syntax of such URI must correspond to the following pattern:
/page1.xml?ContentType="variable"
Where variable is the content type of the targeted part. For example:
/page1.xml?ContentType="application/vnd.ms-metro.rp-fixedpage+xml" When validating digital signatures, Metro consumers MUST process the query component by comparing the content type of the part with the ContentType value specified in the query (in the example above, the value is “application/vnd.ms-metro.rp-fixedpage+xml”). Comparison MUST be case-sensitive and locale-invariant. If the two content types do not match, Metro consumers MUST consider that URI is specifying a missing part. In this case, the validation MUST fail.
... ... ... 5.2.6.3.5
and Algorithms
The required element is an immediate child of . is a required element that specifies the algorithm used for signature generation and validation. The element is an immediate child of . Metro-specific elements MUST use . The element defines the algorithm that yields the from the data (after s are applied). Metro clients MUST be able to support DSA (for ) and RSA-SHA1 (for ) algorithms to produce or validate signatures.
... ... ... ... ... ... Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
5.2 Digital Signatures
49
...
5.2.6.3.6
The Element
The optional element is an immediate child of the element. The element contains an ordered list of child elements describing how the producer digested the data before signing it.
... ... The following transforms MUST be supported by Metro clients producing or consuming packages with digital signatures: 1. XML Canonicalization (c14n) 2. XML Canonicalization with Comments (c14n with comments) 3. Relationships transform (Metro-specific)0. Metro clients validating signed packages MUST fail the validation if other transforms are encountered (including XPath and XSLT). 5.2.6.3.7
Metro-Specific Relationships Transform
Metro producers MAY sign individual relationships to parts in a package, as well as to the Relationships part as a whole. To sign a subset of relationships, the Metro-specific Relationships transform MUST be used. The transform converts the Relationships XML document to another Relationships XML document, filtering relationships which match the specified Id values. The Relationships transform uses the element, an immediate child of the element. Each element transform takes the value of its required Id attribute and uses it to find the relationship with the same Id attribute value. The Id value comparison MUST be case-insensitive and locale-invariant. The filtered relationships appear in the new XML document in the order that the elements are specified in the element. If the specified Id value does not match any relationship Id in the Relationships part, or if the targeted part is not the Relationships part, Metro consumers MUST indicate that the signature is invalid. Producers and consumers MUST perform a Canonicalization transform following the Relationships transform. The example markup below specifies three relationships to sign and then canonicalize.
... ... Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 50
5.2 Digital Signatures
Metro Specification and Reference Guide
... ...
5.2.6.4
Application-Specific s
Application-specific elements in the XML digital signature namespace are optional. When used, an application-specific MUST appear as an immediate child of the element and MAY occur one or more times. Application-specific elements MUST contain XML-compliant data and are not bound by Metro-specific restrictions on URIs and s. However, consumers of Metro packages MAY choose not to process these elements to validate a signature.
... ... ... 5.2.6.5
Summary of Metro Restrictions to the XML Digital Signature Specification
1. s within a element MUST refer only to elements within the same element. s to Metro elements MUST NOT contain transforms other than canonicalization transforms. 2. One and only one Metro-specific element MUST be present in the element. 3. A Metro-specific element MUST contain only and elements (and optionally ).0. a. s within a element MUST refer only to parts within the package. Relative URIs to the local parts MUST have query components specifying part content type. Metro consumers MUST consider s invalid if the part content type does not match the content type specified in the query component of the relative URI. b. s within a element MUST NOT contain transforms other than the canonicalization transforms and Relationships transform described in this specification. c. A Relationships transform, if specified, MUST be followed by a canonicalization transform.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
5.2 Digital Signatures
51
d. The element MUST contain the element described in this specification. .
5.2.7
The Certificate Part
The Metro digital signature infrastructure supports X.509 certificate technology for signer authentication. For information about the X.509 standard, see ITU-T Recommendation X.509 version 3 (1997); and “Information Technology — Open Systems Interconnection — The Directory Authentication Framework” ISO/IEC 9594-8:1997. The certificate used to validate a Metro package may be located in one of the following places: 1. The certificate may be available to the Metro client in a local or remote certificate store or otherwise understood between the creating and consuming applications. 2. The certificate may be stored in its own distinct part in the Metro package. 3. The certificate may be embedded within the XML Signature part.0.
If the certificate is stored in a separate part, the part MUST be targeted from the appropriate XML Signature part(s) using the relationship type defined for certificates. The part holding the certificate MAY be signed. Content types of the certificate parts and the type of the relationship targeting the certificate part from the XML Signature part are defined in Appendix H, “Standard Namespaces and Content Types.” Certificate parts MAY be shared if the same certificate is used to create more than one signature. If no signature part is associated with a certificate part (generally through signature removal) the certificate part SHOULD be removed. For embedding the certificate into the Signature part, Metro clients MUST use the element and its child elements and (all in the XML digital signature namespace).
... ... ...
5.2.8
Generating Signatures
The steps for signing content in Metro documents follow the W3C Recommendation at http://www.w3.org/TR/xmldsig-core/#sec-CoreGeneration, with some specialization for Metro-specific constructs as noted below. The required steps include the generation of elements and the SignatureValue over SignedInfo. The steps below may not be sufficient for signing or validating signatures based on application-specific elements. 5.2.8.1
Reference Generation
1. For each package part being signed: a. Apply the transforms, as determined by the Metro producer, to the content of the part. b. Calculate the digest value using the resulting content of the part.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 52
5.2 Digital Signatures
Metro Specification and Reference Guide
2. Create a element, including the URI of the part with the query component
matching the content type of the target part, necessary transform elements, the digest algorithm, and the .
3. Construct the Metro-specific holding with elements specifying signed parts and with a element.
4. Create a reference to the constructed Metro-specific .0.
When signing data, Metro producers MUST follow the generic creation algorithm described in the W3C Recommendations at http://www.w3.org/TR/xmldsig-core/#sec-CoreGeneration. 5.2.8.2
Signature Generation
1. Create the element with , and at least one . 2. Canonicalize the data and then calculate the using based on the algorithms specified in . 3. Construct a element that includes , elements, (if certificate is embedded in signature), and .0.
5.2.9
Validating Signatures
Metro consumers validate signatures following the steps described in the W3C Recommendation at http://www.w3.org/TR/xmldsig-core/#sec-CoreValidation. When validating digital signatures, Metro consumers MUST verify content type and the digest contained in each in , and validate the signature calculated using . 5.2.9.1
Reference Validation
1. Canonicalize the element based on the specified in the element. 2. For each in : 0. a. Obtain the element to be digested. b. For the Metro-specific element, validate s to signed parts stored in the element. Metro consumers MUST consider s invalid if there is a missing part. c. For the Metro-specific element, validation of s includes verifying the content type of the referenced part and content type specified in the URI query component. Metro consumers MUST consider s invalid if these two values are different. String comparison MUST be case-sensitive and locale-invariant. d. Digest the obtained element using the specified in the element. e. Compare the generated digest value against the in the element of . Metro consumers MUST consider s invalid if there is any mismatch. . 5.2.9.2
Signature Validation
1. Obtain the public key information from or from an external source. 2. Obtain the canonical form of the using the . Use the result and the previously obtained to confirm the stored in the element. The is decrypted using the public key prior to comparison. 0.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
5.3 Thumbnail Parts in Metro Packages
53
5.2.10 Versioning and Extensibility Support
The Metro digital signature infrastructure will support the exchange of signed packages between current and future Metro clients. 5.2.10.1
Using Relationship Types
Future versions of the Metro format will specify distinct relationship types for revised signature parts. Using these different relationships, Metro producers will be able to store separate signature information for current and previous versions, and Metro consumers will be able to choose the signature information they know how to validate. Figure 5–2.
5.2.10.2
Versioning Namespace for Metro Digital Signatures
1. The versioning namespace, as defined in Section 4.2, “Versioning Namespace” on page 26 MUST not be used within the Metro-specific (Id="Metro"). 2. The XML content of Metro package parts which are to be signed may include the versioning namespace. However it is RECOMMENDED that application policies treat as invalid any signature of XML using the versioning namespace. 0.
5.3
Thumbnail Parts in Metro Packages
In a Metro package, images may be stored to help an end-user identify parts of the package or the package as a whole. These images, called “thumbnails”, are generated by the Metro producer and stored in Metro packages as parts. Thumbnail parts MUST be in either jpeg or png format. For information about the content type of a thumbnail part, see Section H.2.1, “Package-Wide Content Types” on page 346. Thumbnail parts MUST be identified by either a part relationship or a package relationship. Metro packages MUST NOT contain more than one thumbnail relationship associated with any single part, or with an entire package. For information about the relationships type for thumbnail parts, see Section H.3.1, “Package-Wide Relationship Types” on page 347.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
55
Part II. T H E R EA C H P A C KA G E F O R MA T
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
57
Chapter 6. The Reach Package Format
The packaging conventions described in Part I, “The Metro Framework” can be used to carry any payload . This specification defines a particular payload that contains a static or “fixed” representation of paginated
content: the fixed payload . A fixed payload has a root FixedDocumentSequence part that contains markup that references FixedDocument parts, which in turn reference FixedPage parts. A package that holds at least one fixed payload, and follows the rules described in this specification, is referred to as a Reach package since it can be consumed by any platform implementing support for the package format. Readers and writers of Reach packages can implement their own parsers and rendering engines based on this specification of the Reach package format. Reach packages address the requirements that information workers have for distributing, archiving, rendering, and processing documents. Using known rendering rules, Reach packages can be unambiguously reproduced or printed from the format in which they are saved, without tying client devices or applications to specific operating systems or service libraries. Additionally, because the Reach package is expressed in a neutral, application-independent way, the content can be viewed and printed without the application used to create the package. The fixed payload requires a sequencing part, the FixedDocumentSequence, for assembling a set of FixedDocument parts. For example, an end user may want to assemble two documents that come from different sources: a two-page cover memo (a FixedDocument) and a twenty-page report (a FixedDocument). Even if a Reach package contains only a single FixedDocument part, the FixedDocumentSequence part is still used. Only one FixedDocumentSequence per fixed payload is REQUIRED. A FixedDocument part has a set number of FixedPage parts. Each page has a fixed size and orientation. The layout of all the elements on a page in a fixed payload is predetermined. This applies not only to graphics, but also to text, which is represented with precise typographic placement. The content of a page (text, graphics, images) is described using a powerful but simple set of visual primitives. Images and fonts are also stored in the fixed payload in Image parts and Font parts respectively, and these are referenced via relationships from the FixedPage parts in which they are used. A single image or font may be shared among multiple FixedPage parts in one or more FixedDocument parts within the fixed payload. Fonts or images external to the Reach package are not allowed. Fonts may be subsetted in order to reduce their size. The fixed payload may also contain thumbnail parts. Thumbnails are small images intended to represent the content of a FixedPage or the entire Reach package. A thumbnail part is attached to a particular FixedPage or the entire package via a relationship. The fixed payload allows inclusion of an annotations part. If included, this part contains additional notes or comments associated with the contents of the fixed payload. Fixed payloads also support PrintTickets . A PrintTicket part provides settings that SHOULD be defined by Reach package writers. PrintTicket parts within a Reach package MUST be processed when the package is printed. PrintTicket parts can be attached in a variety of ways to achieve substantial flexibility. A PrintTicket can be “attached” to an entire Reach package at the level of the FixedDocumentSequence, in which case its settings affect the whole Reach package content. PrintTicket parts can also be attached at lower levels in the structure, for example, to individual FixedPage or FixedDocument parts. These PrintTicket parts provide override settings to be used when printing the part to which they are attached. For more information, see Section 6.1.9, “PrintTicket Parts” on page 68.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 58
6.1
6.1 The Fixed Payload
Metro Specification and Reference Guide
The Fixed Payload
A fixed payload is a payload whose root part is a FixedDocumentSequence part. There can be more than one fixed payload in a Reach package.
A specific relationship type is defined to identify the root of a fixed payload within a Reach package: the Reach Package StartPart relationship. Consumers of Reach packages (viewers or printers) use the Reach Package StartPart relationship to find the fixed payload in the package.
The Reach Package StartPart relationship MUST point to the FixedDocumentSequence part that identifies the beginning of the fixed payload. The payload includes the full closure of all of the parts required for valid processing of the FixedDocumentSequence. All content to be rendered MUST be contained in the Reach package. Table 6–1 lists the valid part types that can be found in a Reach package. Relationships and content types for these parts are defined in Appendix H, “Standard Namespaces and Content Types.” Table 6–1. Part
Description
Required/Optional
FixedDocumentSequence
Specifies a sequence of FixedDocuments.
Required
FixedDocument
Each FixedDocument specifies a set of FixedPages in sequence.
Required
FixedPage
Each FixedPage part represents the content of a page.
Required
Font
Fonts MUST be embedded in a package to ensure reliable reproduction of the glyphs.
Required if are used
Image
If images are used, image parts MUST be included.
Required if is used
Thumbnail
Thumbnail images MAY be included to help end users identify package contents.
Optional
PrintTicket
PrintTickets MAY be included to provide settings to be used when printing the package.
Optional
Annotations
Annotations MAY be included.
Optional
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
6.1 The Fixed Payload
59
Figure 6–1.
Example Reach Package
Primary Fixed Payload
PrintTicket
PrintTicket Part
Sta rtP
ar t
FixedDocumentSequence Part
DocumentReference ta Anno
FixedDocument Part 1
tions
Thumbnail
Annotations Part
Thumbnail Part
PageContent FixedPage Part 1
Required Resource
Image Part
RequiredResource PrintTicket PrintTicket Part
Font Part Required Resource
FixedPage Part N
FixedDocument Part N
Thumbnail
Annotations
Thumbnail Part
Annotations Part
PageContent PrintTicket FixedPage Part 1
PrintTicket Part RequiredResource
Thumbnail Thumbnail Part
FixedPage Part N Thumbnail
Thumbnail Part
Thumbnail
Package Thumbnail Part
Legend Reference Relationship
Required Part
Optional Part
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 60
6.1 The Fixed Payload
6.1.2
Metro Specification and Reference Guide
Fixed Payload Relationships
Internal resources are associated to the parts in a fixed payload by means of relationships and inline references. External resources MUST NOT be referenced in a Reach package. In general, inline resource references are represented inside the referring part in ways that are specific to the content type of the part, that is, in arbitrary markup or an application-specific encoding. Relationships provide a way to represent the kind of connection between a source part and a target resource and allow parts to be related without modifying them. For more information, see Section 2.1.5, “Relationships” on page 11. Relationships names are defined in Appendix H, “Standard Namespaces and Content Types.” Table 6–2. Fixed Payload Relationship Types. Relationship
Description
Core Properties
Relationship from the package to the Core Properties part. Contains the standard package properties such as Creator or DateCreated. For more information, see Section 5.1, “Core Properties” on page 37.
OPTIONAL
Digital Signature Origin
Relationship from the package to the Signature Origin part. Defines the root of digital signatures in the package. For more information, see Section 5.2, “Digital Signatures” on page 38.
OPTIONAL
Digital Signature
Relationship from the Signature Origin part to a Signature part. Signature part contains a digital signature. For more information, see Section 5.2, “Digital Signatures” on page 38.
OPTIONAL
Digital Signature Certificate
Relationship from a Signature part to a Certificate part. Certificate part contains an X509 certificate for validating the signature. For more information, see Section 5.2, “Digital Signatures” on page 38.
OPTIONAL
Reach Package StartPart
Relationship from the package to the FixedDocumentSequence part that is the fixed payload root.
REQUIRED
PrintTicket
Relationship from a FixedDocumentSequence part, a FixedDocument part, or a FixedPage part to a PrintTicket part. PrintTicket parts contain print device configuration information for consumers.
OPTIONAL
Required Resource
Relationship from a FixedPage part to a required resource, such as a Font or Image part. Required resources may be shared between pages.
REQUIRED for each font or image referenced from a FixedPage.
Restricted Font
Relationship from a FixedDocument part to a Font part. Specifies the referenced font as restricted, disallowing any modification or editing of any element text using the referenced font. For more information, see Section 6.1.8.2, “Reach OpenType Font Embedding” on page 65.
REQUIRED for each preview and print font used.
Version 0.7
Required/Optional
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
6.1 The Fixed Payload
Relationship
Description
Annotations
Relationship from a FixedDocument to an Annotations part. Annotations part contains annotations of the FixedDocument contents.
OPTIONAL
Thumbnail
Relationship from the package to an Image part or from a FixedPage to an Image part. Thumbnail part contains a small image representing the contents of the package or page, respectively.
OPTIONAL
DiscardControl
Relationship from an Reach package part to a DiscardControl part. DiscardControl part contains a list of resources that it is safe for the consumer to discard during interleaving. For more information, see Section 6.4.3.1, “The DiscardControl Part” on page 74. .
OPTIONAL
6.1.3
61
Required/Optional
The FixedDocumentSequence Part
The FixedDocumentSequence part is used to bind a set of FixedDocument parts together. For example, a printing client can use the FixedDocumentSequence part to roll-up multiple documents from various sources into a single package before sending the contents to the printer. The FixedDocumentSequence is REQUIRED as the only valid root of a fixed payload. The markup in the FixedDocumentSequence part specifies each FixedDocument in the fixed payload, in sequence using elements under the element. The content type of the FixedDocumentSequence part is defined in Appendix H, “Standard Namespaces and Content Types.” The FixedDocumentSequence part MAY specify a version-control mechanism. If versioning markup is used, the part must include a reference to the versioning namespace. For more information, see Chapter 4, “Versioning and Extensibility”. For more information, see Section 7.5.1, “FixedDocumentSequence Element” on page 81.
6.1.4
The FixedDocument Part
The FixedDocument part is a common, easily indexed root for all pages within the document. Each element in the references the FixedDocument part name by absolute or relative URI. The markup in a FixedDocument part specifies the pages of a document in sequence under the element using elements. The content type of the FixedDocument part is defined in Appendix H, “Standard Namespaces and Content Types.” The FixedDocument part MAY specify a version-control mechanism. If versioning markup is used, the part must include a reference to the versioning namespace. For more information, see Chapter 4, “Versioning and Extensibility”. For more information, see Section 7.5.2, “FixedDocument Element” on page 82.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 62
6.1.5
6.1 The Fixed Payload
Metro Specification and Reference Guide
The FixedPage Part
The FixedPage part contains all of the elements to be rendered on a particular page.
Each element in the FixedDocument part references a FixedPage part name by absolute or relative URI. Each FixedPage part specifies the contents of a page under a element, using and elements grouped by the element.
The content type for the FixedPage part is defined in Appendix H, “Standard Namespaces and Content Types.” For more information, see Section 7.5.3, “FixedPage Element” on page 85.
6.1.6 6.1.6.1
Image Parts Supported Formats
Images in JPEG, PNG, and TIFF formats can be used in Reach packages. Images MUST use the requiredresource relationship. For more information, see Section H.3.2, “Reach-Specific Relationship Types” on page 347. JPEGs are used by creating an with an ImageSource attribute which references a part with the appropriate content type. For more information, see Section H.2.2, “Reach-Specific Content Types” on page 346. It is RECOMMENDED that JPEG image parts have a part name ending in the extension “.jpg”. Embedded color profiles contained in JPEG image files SHOULD be used by a Metro Reach consumer. JPEG image parts MUST contain images which conform to the JPEG specification cited in Section 1.1, “Standards and Conformance” on page 3. PNGs are used by creating an with an ImageSource attribute which references a part with the appropriate content type. For more information, see Section H.2.2, “Reach-Specific Content Types” on page 346. It is RECOMMENDED that PNG image parts have a part name ending in the extension “.png”. A PNG image used in a Reach package MAY contain the optional tags sICC, cHRM, gAMA, sBIT, sRGB, but a Reach consumer SHOULD ignore these tags. Embedded color profiles contained in PNG image files SHOULD be used by a Metro Reach consumer. PNG image parts MUST contain images which conform to the PNG specification cited in Section 1.1, “Standards and Conformance” on page 3. TIFFs are used by creating an with an ImageSource attribute which references a part with the appropriate content type. For more information, see Section H.2.2, “Reach-Specific Content Types” on page 346. It is RECOMMENDED that TIFF image parts have a part name ending in the extension “.tif”. Embedded color profiles contained in TIFF image files SHOULD be used by a Metro Reach consumer. TIFF image parts MUST contain images which conform to the TIFF specification cited in Section 1.1, “Standards and Conformance” on page 3.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
6.1.6.1.1
6.1 The Fixed Payload
63
Supported TIFF 6.0 Tags
Reach consumers MUST support baseline TIFF 6.0, with some extensions noted below. Specifically, the following tags MUST be supported for various image types. If a Reach consumer encounters a tag that is not included below, it SHOULD ignore that tag. Bilevel Images •
PhotometricInterpretation: 0 and 1
•
Compression: 1, 2 or 32773
•
ImageLength
•
ImageWidth
•
ResolutionUnit: 1, 2 or 3
•
XResolution
•
YResolution
•
RowsPerStrip
•
StripOffsets
•
StripByteCounts
Palette Color Images •
ColorMap
•
BitsPerSample: 8
•
Compression: 1 or 32773
•
PhotometricInterpretation: 3
•
ImageWidth
•
ImageHeight
•
StripOffsets
•
RowsPerStrip
•
XResolution
•
YResolution
•
ResolutionUnit: 1, 2 or 3
•
StripByteCounts
RGB Images •
ImageWidth
•
ImageHeight
•
BitsPerSample: (8,8,8)
•
Compression: 1 or 32773
•
PhotometricInterpretation: 2
•
StripOffsets
•
SamplesPerPixel: 3
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 64
6.1 The Fixed Payload
•
RowsPerStrip
•
StripByteCounts
•
XResolution
•
YResolution
•
ResolutionUnit: 1, 2 or 3
•
PlanarConfiguration: 1
Metro Specification and Reference Guide
CMYK Images (TIFF extension) •
ImageWidth
•
ImageHeight
•
BitsPerSample: (8,8,8,8)
•
Compression: 1 or 32773
•
PhotometricInterpretation: 5
•
InkSet: 1
•
NumberOfInks: 4
•
StripOffsets
•
SamplesPerPixel: 4
•
RowsPerStrip
•
StripByteCounts
•
XResolution
•
YResolution
•
ResolutionUnit: 1, 2 or 3
•
PlanarConfiguration: 1
6.1.7
Thumbnail Parts
Thumbnail images may be attached using a relationship to the FixedPage parts in Reach package. Only one thumbnail per part is allowed. Relationships to thumbnail parts are defined in Appendix H, “Standard Namespaces and Content Types.” Thumbnail parts MUST be in either JPEG or PNG formats. The content type of a thumbnail part MUST be either “image/jpeg” or “image/png”. For FixedPage parts, thumbnail images may be used that are snapshots of the contents of the FixedPage. These thumbnails can enable a user of a viewing application to choose the page to view. For more information, see Section 5.3, “Thumbnail Parts in Metro Packages” on page 53.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
6.1.8
6.1 The Fixed Payload
65
Font Parts
Metro packages support the OpenType font format. For more information about the OpenType specification, see Section 1.1, “Standards and Conformance” on page 3. To support portability, Unicodeencoded fonts SHOULD be used.
Font parts are referenced using the FontUri attribute of the element. For example, to reference the font part “../Fonts/Times.OTF”, the value of the FontURI attribute is “../Fonts/Times.OTF”. Font references MUST be internal to the package. External references to fonts are invalid. If the referenced font part is a TrueType Collection (containing multiple font faces), the fragment portion of the URI indicates which font face should be used. The use of URI fragments is specified in BNF of Generic URI Syntax at http://www.w3.org/Addressing/URL/5_URI_BNF.html. The value of the FontURI fragment MUST be between 0 and n-1, where n is the number of font faces contained in the TrueType Collection. For example, to reference the first font face in the font part “../Fonts/CJKSuper.TTC”, the FontUri attribute is ”../Fonts/CJKSuper.TTC#0”. Content types for fonts differ depending on whether the font is non-obfuscated or obfuscated (see Section 6.1.8.2, “Reach OpenType Font Embedding” on page 65). Content types are summarized in Appendix H, “Standard Namespaces and Content Types.” Fonts parts use the required resource relationship. 6.1.8.1
Subsetting Fonts
Fixed payloads represent text using the element. Since the format is fixed, it is possible to subset fonts to contain only the glyphs required by the package in which the font is used. Therefore, fonts in Reach packages may be subsetted based on glyph usage. Although a subsetted font will not contain all the glyphs in the original font, the subsetted font MUST be a valid OpenType font file. Requirements for valid OpenType font files are described in The OpenType Font File at http://www.microsoft.com/typography/otspec/otff.htm. 6.1.8.2
Reach OpenType Font Embedding
Protecting intellectual property of font vendors is a goal of the Metro Reach document format. Consequently, Reach producers and consumers MUST observe the guidelines and mechanisms described below in order to honor the licensing rights specified in OpenType fonts. The licensing rights of an OpenType font are specified in the fsType field of the required OS/2 table of the font. Table 6–3 lists the bit mask values that can appear in arbitrary combinations in the fsType field. Also listed are short descriptions of the licensing right intents and requirements or recommendations. These requirements represent the “rules” that Reach producers and consumers must follow in order to respect licensing rights specified in the font. If the fsType field contains a combination of multiple bit mask values, ALL of the indicated rules apply. For further details on licensing rights of OpenType fonts, please see the description of the OS/2 table in OS/2 and Windows Metrics at http://www.microsoft.com/typography/otspec/os2.htm#fst.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 66
6.1 The Fixed Payload
Metro Specification and Reference Guide
Table 6–3. Bit/Mask
Licensing Right Intent
Reach Producer Rules
Reach Consumer Rules
- / 0x0000
Installable embedding
SHOULD do embedded font obfuscation1, 2
SHOULD NOT extract or install permanently2
0 / 0x0001
Reserved, must be 0
1 / 0x0002
Restricted license embedding. If ONLY this bit is set, the font MUST NOT be modified, embedded or exchanged in any manner without obtaining permission from the legal owner.
MUST NOT embed. SHOULD generate a
MUST render embedded images.
2 / 0x0004
Preview and print embedding: Font may be embedded and temporarily used on remote systems. However, documents containing ANY preview and print fonts MUST NOT be modified or edited.
3 / 0x0008
Editable embedding
4-7
Reserved, must be 0
8 / 0x0100
No subsetting
filled with an referencing an image of rendered characters. A future draft of this specification will define mechanisms for combining accessibility-enabling information with the image of rendered characters.
A future draft of this specification will define mechanisms for combining accessibility-enabling information with the image of rendered characters.
MUST do embedded font obfuscation1.
MUST NOT extract or install permanently.
MUST add a Restricted Font relationship to FixedDocument part of document containing the font3.
MUST NOT modify or edit Reach document hierarchy starting from .
MUST do embedded font obfuscation1
MUST NOT extract or install permanently
MUST do embedded font obfuscation1.
MUST NOT extract or install permanently
MUST NOT subset font before embedding. 9 / 0x0200
Bitmap embedding only
MUST do embedded font obfuscation1.
MUST NOT extract or install permanently
MUST ONLY embed bitmap characters contained in the font. If no bitmap characters are present in the font, MUST NOT embed. 10-15
Version 0.7
Reserved, must be 0
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
6.1 The Fixed Payload
67
1. See Section 6.1.8.3, “Embedded Font Obfuscation” below for details.
2. Although the licensing intent of the font allows embedding of un-obfuscated fonts and installation of the font on a remote client system under certain conditions, this is NOT RECOMMENDED in Reach packages. Microsoft implementations for Reach packages always does obfuscated font embedding and does not extract or permanently install the font. However, there are vertical solution scenarios in which an implementation of Reach packages may benefit from un-embedded font obfuscation, and in those cases a Reach package implementation MAY omit obfuscation or MAY extract and install the embedded font. 3. See Section 9.1.9, “Device Fonts” on page 143 for details. 6.1.8.3
Embedded Font Obfuscation
Embedded font obfuscation is a means of preventing casual misappropriation of embedded fonts. Specifically, embedded font obfuscation prevents end-users from using standard ZIP utilities to extract fonts from Metro Reach Document files and install them on their systems. Embedded font obfuscation is NOT considered a strong encryption of the font data. Embedded font obfuscation achieves these goals: 1. Obfuscated font files are embedded within a Metro Reach Document package in a form which cannot be directly installed on any client OS. 2. Obfuscated font files are closely tied to content referencing them. Therefore, it becomes nontrivial to misappropriate fonts by moving them from one package to another package. 3. The way obfuscated font files are tied to content referencing them still allows merging documents. 0. In order to decide when fonts have to be obfuscated prior to embedding, refer to the table in Section 6.1.8.2, “Reach OpenType Font Embedding” on page 65. If a Reach producer needs to do embedded font obfuscation, the producer MUST satisfy these requirements: 1. Generate a 128-bit GUID (Globally Unique Identifier) for the font to be obfuscated. Instead of a true GUID, a 128-bit random number MAY be used. 2. Generate a part name for the obfuscated font using the GUID. The last segment of the part name MUST be of the form “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX” or “XXXXXXXX-XXXXXXXX-XXXX-XXXXXXXXXXXX.ext” where each “X” represents a placeholder for one hex-digit of the 128-bit GUID. The part name MAY have an arbitrary extension (identified by the placeholder “.ext”). It is RECOMMENDED that the extension be “.ODTTF” 3. The content type for the part containing the obfuscated font MUST match the definition in Appendix D. 4. XOR the first 32 bytes of the binary data of the font with binary representation of the GUID, repeating the GUID once, starting with the least significant byte of the binary GUID representation. The result is an obfuscated font. 5. Store the obfuscated font in a part with the generated name.0. When processing fonts in a Reach package, a Reach consumer MUST follow these steps: 1. If the content type of the part containing the font is not the obfuscated font content type as specified in Appendix D, process the font without any de-obfuscation steps. 2. For font parts with the obfuscated font content type as specified in Appendix D, de-obfuscate the font by following these rules:0. a. Remove the extension from the last segment of the name of the part containing the font.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 68
6.1 The Fixed Payload
Metro Specification and Reference Guide
b. Convert the remaining characters of the last segment to a GUID using the format specification described above. c. XOR the first 32 bytes of the binary data of the obfuscated font with binary representation of the GUID, repeating the GUID once, starting with the least significant byte of the binary GUID representation. The result is an un-obfuscated font.
d. Use the un-obfuscated font for the duration of processing the document, but do not leave any local or otherwise user-accessible copy of the un-obfuscated font behind. .
6.1.9
PrintTicket Parts
The purpose of the PrintTicket part is to provide user intent and device configuration information to printing consumers. PrintTicket parts can be attached only to FixedDocumentSequence, FixedDocument and FixedPage parts in the Reach package and only in the manner specified in Section 6.3, “Validity Rules for Reach Packages” on page 71. 6.1.9.1
PrintTicket Defintion
The PrintTicket is an XML format for describing print settings in a consistent, accessible and extensible manner. For more information, see Section 1.1.16, “Print Schema” on page 4. Within the context of the Reach package, the PrintTicket is defined by the Reach package producer. Producers should note that a Reach package may be printed on various devices, and that the settings included in the PrintTicket SHOULD support portability. Producers and consumers should note that no PrintTicket keywords defined in the Print Schema are applicable to Reach packages. For more information, see Section 1.1.16.1, “Print Schema Keywords” on page 4. 6.1.9.2
Mapping PrintTicket Parts to the Fixed Payload Parts
The PrintTicket defines a hierarchy of print settings to identify the applicability of a setting to different content levels within a print job. More specifically, the PrintTicket supports a hierarchy that is rooted in the print job. From the print job, multiple documents are derived. From each document, multiple pages are defined. A PrintTicket can be associated with each level in this hierarchy. These PrintTicket parts are labeled “job-level”, “document-level”, and “page-level” respectively. Within each PrintTicket, print settings (i.e., user intent and device configuration) are defined. Each print setting has a “scoping prefix” to indicate the level at which it applies. For example, “JobDuplex” is a joblevel setting, “DocumentStaple” is a document-level setting and “PageOrientation” is a page-level setting. Settings in level-specific PrintTicket parts are restricted by this scoping prefix. A level-specific PrintTicket MUST contain only settings scoped to the current level and child levels. More specifically, job-level PrintTicket parts MUST contain only job-, document-, and page-scoped settings; document-level PrintTicket parts MUST contain only document- and page-scoped settings; and page-level PrintTicket parts MUST contain only page-scoped settings. Within the Reach package, there is a direct mapping between the PrintTicket levels and the fixed payload parts. Job-level PrintTicket parts MUST be associated only with FixedDocumentSequence parts. Documentlevel PrintTicket parts MUST be associated only with FixedDocument parts. Page-level PrintTicket parts MUST be associated only with FixedPage parts. PrintTicket parts are associated with parts via the PrintTicket relationship defined in Appendix H, “Standard Namespaces and Content Types.” 6.1.9.3
Processing PrintTicket Parts Within the Reach Package
A Reach package printing consumer MUST process all PrintTicket parts within the Reach package. When processing a PrintTicket, a Reach consumer MUST first validate the PrintTicket according to the methods defined in the PrintTicket specification. Following validation, the printing consumer MUST properly interpret the print settings according to the following rules for merging two PrintTicket parts.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
6.1 The Fixed Payload
69
Print settings are expressed by scoped Print Schema Framework elements. Elements may interact between different levels in the PrintTicket hierarchy. Elements that interact between PrintTicket levels MUST be specified at the root level of each level ticket. A merge conflict between elements is defined as the same root level element, as denoted by the XML name attribute appearing in multiple level tickets.
There are two options for interactions:
1. If there is no merge conflict, a prefix-scoped element MUST be pushed down, or inherited, from a more general ticket to a more specific ticket. This case is isomorphic to the case where both tickets contain the identical element.
2. If there is a merge conflict, the setting from the most specific ticket takes precedence. That is, a page-scoped setting in a page-level PrintTicket MUST overwrite an identical page-scoped setting in a document-level or job-level PrintTicket. Similarly, a document-scoped setting in a documentlevel PrintTicket MUST overwrite an identical document-scoped setting in a job-level PrintTicket.0. To determine the print settings in the Reach package the following algorithm should be applied: 1. Validate the job-level PrintTicket associated with the FixedDocumentSequence by merging and validating the PrintTicket with the default PrintTicket for the print consumer. Call the resulting ticket the “validated job-level PrintTicket”. If no job-level PrintTicket is supplied, use the default PrintTicket. 2. For each FixedDocument referenced by the FixedDocumentSequence, merge and validate the document-level PrintTicket with the validated job-level PrintTicket. Call the resulting ticket the “validated DocumentX-level PrintTicket”, where X represents the Xth FixedDocument in the FixedDocumentSequence. If no document-level PrintTicket is supplied for a particular document, use the validated job-level PrintTicket. 3. For each FixedPage referenced by each FixedDocument, merge and validate the page-level PrintTicket with the validated DocumentX-level PrintTicket, where DocumentX represent the parent FixedDocument of the FixedPage. Call the resulting ticket the “validated PageXY-level PrintTicket”, where X represents the Xth FixedDocument in the DocumentSequence and Y represents the Yth FixedPage in the Xth FixedDocument. If no page-level PrintTicket is supplied for a particular document, use the validated DocumentX-level PrintTicket.0.
6.1.10 Annotations Part Reach producers and consumers MAY include support for storing annotations of a Reach package in the fixed payload itself. Producers storing annotation information inside the fixed payload MUST conform to the following requirements. Annotation data MUST be stored in a separate Annotations part, with an associated relationship on the FixedDocument. The relationship name MUST follow that specified in Section H.1.2, “Reach-Specific Namespaces” on page 345. The Annotations part MUST have a content type that indicates the specification to which the annotations conform. Format of the content in the Annotations part is not yet ready for review.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 70
6.2 Specifying Content Structure
6.2
6.2.1
Metro Specification and Reference Guide
Specifying Content Structure Reading Order
Because Metro Reach consumers MAY rely on the markup order for purposes of determining reading order, Metro Reach documents SHOULD structure the markup order within all FixedPage parts in the order in which any content contained on that page is intended to be read. Structuring markup order to match reading order is strongly RECOMMENDED.
6.2.2
Hyperlinks
Consumers of a Reach package MAY enable user interactivity. If they do so, consumers SHOULD support hyperlink activation and addressing into the Reach package by hyperlinks. 6.2.2.1
Hyperlink Activation
Hyperlinks are specified inline in the FixedPage part on any , , or element by including the FixedPage.NavigateUri attribute set to the hyperlink destination URI. If hyperlinked or elements are rendered overlapping on the page, the consumer MUST treat the topmost element as the only accessible hyperlink that may be activated. When activating a hyperlink, the consumer SHOULD load the specified resource if the consumer understands the URI type. If the URI is an internal reference to the Reach package, the consumer SHOULD navigate to that URI. If the producer specifies the FixedPage.NavigateUri attribute on a , the consumer MUST treat all elements contained in that as having an associated hyperlink, unless overridden by a nested element specifying the FixedPage.NavigateUri attribute. Relative internal hyperlinks between FixedPage parts MUST specify the named address, at minimum, relative to the FixedDocument part, for example,
FixedPage.NavigateUri="../MyDocument#MyAddress" Producers of Reach packages may mark any , , , or element as an addressable named location within the Reach package by specifying the Name attribute. The Name attribute value SHOULD be unique within the scope of the FixedDocument. If it is not, only the first occurrence of the named address is addressable. The behavior of hyperlinks for FixedDocumentSequence is still under design. It is RECOMMENDED that Name attribute values are unique within an entire FixedDocumentSequence. If they are not, only the first occurrence of the named address is addressable from external to the Reach package. For internal-referencing hyperlinks within a particular FixedDocument, the consumer MUST identify the named address within the FixedDocument containing the hyperlink before identifying a named address from a FixedDocument which precedes it in the FixedDocumentSequence. In order to be addressable, the named address MUST appear in the element in the FixedDocument part . If a named address appears in the element in the FixedDocument part but is not found in the Name attribute of an element within the associated , the consumer MUST treat the top of the associated as the named address. If the named address is not found, the Reach consumer MUST ignore the fragment portion of the URI.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
6.2.2.2
6.3 Validity Rules for Reach Packages
71
Reach Package URI Fragments
A Reach package specifies two unique forms of URI fragment identifiers to address locations within a Reach package. The first is a named address, for example, “http://metro/MyPackage#MyAddress” where “MyAddress” is a named address within the FixedDocument (see Section 11.3, “Hyperlink Attributes” on page 192). The second is an absolute page number within the Reach package, for example, “http://metro/MyPackage#15” where “15” references the FixedPage part associated with the 15th entry in the FixedDocument part.
If the Reach package uses a FixedDocumentSequence, a page number fragment identifier refers to the absolute page number in the FixedDocumentSequence. For example, if a Reach package has a three-page FixedDocument, followed by a ten-page FixedDocument, followed by an eight-page FixedDocument, then the fragment identifier “#15” would refer to the second page of the third FixedDocument in the FixedDocumentSequence.
6.2.3
Accessibility
The Accessibility features specification is not yet ready for review.
6.3
Validity Rules for Reach Packages
Because a Reach Package is designed to be a “view-and-print-anywhere” document, readers and writers of Reach Packages must share common, unambiguously defined expectations of what constitutes a valid Reach Package. The following conformance rules describe a valid Reach Package: •
A Reach Package MUST have at least one fixed payload root that is a FixedDocumentSequence.
•
A Reach Package MUST have one and only one Reach Package StartPart relationship to a fixed payload root. This is the primary fixed payload root.
•
PrintTicket parts MAY be attached (using the Print Ticket relationship) to any FixedDocumentSequence parts, FixedDocument parts identified in the FixedDocumentSequence(s) or any of the FixedPage parts identified in the FixedDocument(s).
•
Any FixedDocumentSequence, FixedDocument, or FixedPage part reachable from the primary fixed payload root or its related parts by relationship or by a or Source attribute MUST have no more than one PrintTicket attached.
•
Every Font part reachable from the primary fixed payload root or its related parts by relationship or by a or Source attribute MUST meet the font format rules defined in Section 6.1.8, “Font Parts” on page 65.
•
Every Image part reachable from the primary fixed payload root or its related parts by relationship or by a or Source attribute MUST meet the image format rules defined in Section 6.1.6, “Image Parts” on page 62.
•
•
For every font or image referenced from a FixedPage, there MUST be a required resource relationship from the referencing FixedPage to the referenced part. The required resource relationship is defined in Appendix H, “Standard Namespaces and Content Types.” The Name attribute for every , , , and element MUST conform to the XML-subset naming conventions described in Section 11.3.1, “Name Attribute” on page 192.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 72
6.4 Interleaving Optimizations for Reach Packages
6.4
Metro Specification and Reference Guide
Interleaving Optimizations for Reach Packages
Interleaving is OPTIONAL. Correct interleaving of a Metro package applies to the physical organization of the package, rather than to the logical structure. The goal of correct interleaving is to allow a consumer to linearly process the bytes that make up the physical package from start to end of the package in a “context-free” way. In other words, the consumer can make correct determinations about types of logical parts and the presence of relationships on a logical part when linearly consuming the package. The consumer is never required to back up to parts previously encountered and revise its determination of content type or presence of relationships. In order to guarantee correct interleaving, the producer of a Reach Package MUST follow these rules: •
When mapping a logical part to a physical format, the producer MUST write any portion of the content type stream that contains a content type default or override affecting the logical part to the physical package so that portion appears linearly BEFORE the affected part.
•
When mapping a logical part which has attached relationships to the physical format, the producer MUST write AT LEAST the first piece of the relationship part to the physical package, so it appears linearly NO LATER than DIRECTLY AFTER the last piece of the part.
6.4.1
Optimizing Interleaving Order
A producer of a Reach Package MAY optimize the interleaving of parts to help a consumer avoid stalls during read-time streaming, and to allow a consumer to manage its memory resources more efficiently. An optimal interleaving scheme would interleave parts so that each part required to consume a single page (FixedPage, images and fonts) is contained in the package in its entirety, prior to the FixedPage part being referenced from a FixedDocument. For example, for a sequence of two FixedDocuments, the first of which having two fixed pages and the second having one, a possible interleaving is: Table 6–4. Part/Piece
Markup
Font1.ttf
...binary font data...
Other resources
...resource data...
Page1
Page1.rels
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
Part/Piece
6.4 Interleaving Optimizations for Reach Packages
73
Markup
FixedDocument1/[0].piece
Sequence1/[0].piece
_rels/.rels/[0].piece
Page2
...
FixedDocument1/[1].last.piece
Page3
...
FixedDocument2
Sequence1/[1].last.piece
_rels/.rels/[1].last.piece
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 74
6.4 Interleaving Optimizations for Reach Packages
6.4.2
Metro Specification and Reference Guide
Consuming Interleaved Packages
Regardless of the interleaved structure of a Reach package, a consumer MUST be able to consume the package. A consumer without the resources to process a part MUST indicate an error condition. Such a resource constraint exists when a consumer does not have enough memory resources to hold the amount of the package required for resolving all the references for processing a part. To address resource constraints: •
A consumer MAY discard FixedPage parts once they have been processed.
•
A consumer MAY discard FixedDocument and Sequence parts after all their respective children have been processed, and the closing or tag has been processed.
•
In the absence of explicit directives to the contrary (described in Section 6.4.3, “Reach Consumers with Resource Constraints” on page 74), a consumer MAY discard parts as directed by the DiscardControl part. The consumer MUST NOT discard any other parts (for example, parts containing fonts, images, or other resources) unless the consumer has the ability to access the parts again.
If a consumer encounters a reference to an unknown part, it MUST continue to receive further bytes of the package until the unknown part has been transmitted OR until the end of the package is reached (indicating an error condition).
6.4.3
Reach Consumers with Resource Constraints
To produce a Reach package for streaming to a consumer with limited memory resources, some producers MAY choose a suitable interleaving order by modeling the resource management behavior of the consumer. These producers, referred to as drivers in this specification, must have specific knowledge regarding the consumer of the Reach package. Due to resource constraints, some consumers of Reach packages will not be able to consume arbitrary Reach packages and will always require assistance from an external driver. When some consumers with limited memory resources receive a Reach package in a streaming fashion, there may be no opportunity to discard parts when necessary and reload them again when needed. A Reach producer targeting such a consumer will need to follow a strategy to: •
Conservatively model the memory usage of the device
•
Interleave pieces of parts in the correct order
•
Decide when certain parts may be discarded by the consumer and inform the consumer within the package stream (see Section 6.4.3.1, “The DiscardControl Part” below)
•
Add to the package a uniquely-named copy of a resource that may have been discarded, if the resource is referenced by a part sent later in the stream
6.4.3.1
The DiscardControl Part
In addition to optimally ordering interleaved parts, producers may support consumers with resource constraints by using the DiscardControl part. The DiscardControl part is a well-known part containing a list of resources that it is safe for the consumer to discard. DiscardControl parts are stored in Reach packages in an interleaved fashion. DiscardControl parts are targeted with a DiscardControl package relationship, as specified in Appendix H, “Standard Namespaces and Content Types.” Parts that may be discarded are identified by their part names, as shown below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
6.4 Interleaving Optimizations for Reach Packages
75
...
In some cases, a producer may rewrite the contents of a package so that a part is provided more than once, allowing a consumer to discard a part in order to free resources for additional processing. Each instance of a part MUST be stored as a new, uniquely named part in the package.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
77
Chapter 7. Reach Markup Basics 7.1
Reach and Other Markup Standards
Reach markup has been specified to facilitate the independent development of multiple compatible implementations of systems that produce or consume Reach packages. However, it has also been designed to share concepts with portions of the Microsoft WinFx programming platform. The Reach graphics rendering model is shared with that of WinFx Avalon, assuring fidelity between onscreen display and printed output. The syntax of FixedPage, FixedDocument, and FixedDocumentSequence markup is compatible with that of WinFx XAML. The XML elements, attributes, and attribute values are a subset of those provided by Avalon. The relationship between Reach markup and WinFx technologies does not impose any requirement on system implementations. Support for Reach markup does not require incorporation of WinFx, Avalon, or managed code. However, this relationship with WinFx technologes does make it easy for markup producers to adapt Reach markup for further use in the Avalon framework. Within the Avalon framework, producers can supplement that markup with additional Avalon features. The Reach markup design reflects the tension between two, sometimes competing, goals: 1. To minimize incompatibility between independent implementations, the Reach markup should be “parsimonious”, that is, it should include the minimum set of primitive operations and markup constructs necessary to render graphics with full-fidelity. Redundancy in the specifications would increase the opportunity for multiple implementations — including printer-resident raster imageprocessors (RIPs), viewers, and interactive applications — to introduce accidental incompatibilities. Furthermore, such redundancy would increase the cost of implementation and testing, and the required memory footprint for many implementations. 2. Reach markup should also be relatively compact. The most common graphical primitives for vector graphics and text-rendering should have compact representations. Bloated representations detract from the performance of systems handling Reach packages. As byte-count increases, so does communication time. Although compression ameliorates such increases in communication time, it cannot eliminate it. Similarly, bloat in the markup diminishes the raw performance of software systems which process it.0. Reach markup has been designed in anticipation of future evolution of its specification. Furthermore, it allows for third-parties to extend the markup so that producers and consumers can cooperate to use thirdparty-defined extensions. To achieve these goals, Reach markup incorporates the versioning and extensibility specification described in Chapter 4, “Versioning and Extensibility”. That specification is shared with WinFX XAML.
7.2
Reach Markup Model
Reach markup is an XML-based markup language, based on XML elements, attributes, and namespaces. The schema for Reach markup includes only XML elements, comments, and whitespace. Arbitrary character data intermingled in the markup is not allowed. Three XML namespaces are defined in this specification for inclusion in Reach markup. One such namespace references the versioning and extensibility markup as defined in Chapter 4, “Versioning and Extensibility”. The principal namespace used for elements and attributes in the FixedPage markup is the Reach package namespace, as defined in Appendix H, “Standard Namespaces and Content Types.” Finally, FixedPage markup introduces the concept of resources (which uses a third namespace) as described in Section 11.4, “Resource and Resource References” on page 194.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 78
7.2 Reach Markup Model
Metro Specification and Reference Guide
Although FixedPage markup is expressed using XML elements and attributes, its specification is based upon a higher-level abstract model of “contents” and “properties”. All FixedPage elements are expressed as XML elements. Only a few FixedPage elements can hold “contents”, expressed as child XML elements. However, a property value may be expressed by using either an XML attribute or a child XML element.
Reach markup also depends upon the concepts of resource dictionary and resources. The combination of
a resource dictionary and multiple resources allow multiple markup elements to share common propertyvalues.
7.2.1 Property Syntax There are three forms of markup which can be used to specify the value of a FixedPage markup property. If the property is specified using a resource reference , the property name is expressed as an XML attribute name and a special syntax for the attribute value indicates the presence of a resource reference. The syntax for expressing resource references is described in Section 11.4, “Resource and Resource References” on page 194. Some property values that are not specified as resource references may be expressed in XML using a nested child XML element identifying the property whose value is being set. For more information, see Section 7.2.3, “Property Element Syntax” below. Finally, some non-resource reference property-values can be expressed as simple-text strings. The set of such property-values is described in Section 7.2.2, “Property Attribute Syntax” below. These property values are expressed using simple XML attribute syntax. No property may be set more than once for any element, regardless of the syntax used for specifying a value.
7.2.2 Property Attribute Syntax For a property expressible as a string, XML attribute syntax may be used to specify a property value. For example, given the FixedPage markup element called “SolidColorBrush,” with the property called “Color”, the following syntax can be used to specify a property value:
7.2.3 Property Element Syntax Some property values cannot be expressed as a simple string. In these cases, an XML element is used to describe the property value. Such property values cannot be expressed using property attribute syntax, but they can be expressed using property element syntax. In property element syntax, a child XML element is used. The element name is derived from a combination of a parent element name and the property name, separated by a “.” character. When specifying a property value using property element syntax, the child XML elements representing properties MUST appear before the child XML elements representing “contents”. The order of individual property element child elements is important: they MUST occur before any contents of the parent element and they MUST appear in the sequence specified in the schema. For example, when using both Clip and RenderTransform properties of the element, both MUST appear before any and contents of the :
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
7.3 Language in Reach Packages
79
In certain cases, an attribute may be specified as either a simple attribute, through the use of an abbreviated descriptive syntax (e.g., geometries or matrices), or in the more complex property element syntax. A consumer MUST treat a property that is specified in both ways as an error.
7.3
Language in Reach Packages
The language of the content in a Reach package MUST be identified in the Reach markup. Reach markup specifies the language of its content by using the XML-standard xml:lang attribute, the value of which is inherited by child elements. The xml:lang attribute is defined in the XML standard (found at http://www.w3.org/TR/REC-xml/). This attribute is REQUIRED for elements and MAY be used with the , , and elements. It is invalid to use the xml:lang attribute on any other Reach markup elements. When the language of the content is unknown, the xml:lang value “und” (undetermined) MUST be used. Language information is critical in supporting the following application features, as well as many others: •
Selection of a text-to-speech dictionary by a screen reading program (providing accessibility of the document content to persons with disabilities)
•
Selection of a spelling checker for text copied to another document
•
Selection of a grammar checker for text copied to another document
•
Rendering the font correctly when copying the text to another document
This last example refers to instances where multiple languages share the same basic script. For example, the Devanagari script is shared by the Indic languages Bhojpuri, Bihari, Hindi, Kashmiri, Konkani, Marathi, Nepali and Sanskrit. Each of these languages has certain glyph sequences that are rendered differently for that language. When text is copied out of a Reach package, the specific language of the copied UnicodeString characters is needed to insure that the rendering of the glyphs is properly transferred when they are pasted into another application. This type of font characteristic applies to most Indiclanguage fonts, some East Asian-language fonts, and others as well.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 80
7.4
7.4 Diagram Notes
Metro Specification and Reference Guide
Diagram Notes
This chapter and those that follow describe each markup element, including the use of element diagrams. When reading these diagrams, there are a few special symbols that have meaning. These are described in the table below. The diagrams appear as a tree with the parent element on the left and the attributes and child elements to the right.
Required Element: This box represents an element that MUST appear exactly once in markup when the parent element is included. The "plus" and "minus" symbols on the right of these boxes have no semantic meaning. Optional Element: This box represents an element that can appear zero or one times in markup when the parent element is included. Range Indicator: These numbers indicate that the designated element or choice of elements can appear in markup any number of times within the range specified. Attribute Group: This box indicates that the enclosed boxes are each attributes of the parent element. Solid-border boxes are required attributes; dashed-border boxes are optional attributes.
Sequence Symbol: The element boxes connected to this symbol can only appear in markup in the illustrated sequence, from top to bottom. Choice Symbol: Only one of the element boxes connected to this symbol can appear in markup. Type Indicator: The elements within the dashed box are of the complex type indicated, according to Appendix G, “Metro Schema”.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
7.5
7.5.1
7.5 Document Markup
81
Document Markup
FixedDocumentSequence Element
element FixedDocumentSequence diagram
annotation Specifies a sequence of FixedDocuments.
Only FixedDocument children can be referenced from within a FixedDocumentSequence part. FixedDocuments are referenced using the element and a Source attribute that specifies the URI of the FixedDocument part.
7.5.1.1
DocumentReference Element
element DocumentReference diagram
attributes Name Source
Type
Use
Default
Fixed
xs:anyURI required
Annotation Specifies the URI of the FixedDocument part.
annotation Contains a reference to a FixedDocument part.
The element is used to specify a FixedDocument part within a FixedDocumentSequence.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 82
7.5 Document Markup
7.5.2
Metro Specification and Reference Guide
FixedDocument Element
element FixedDocument diagram
annotation Binds an ordered sequence of FixedPages together into a single multi-page document.
The FixedDocument part contains markup with a single element root. The document structure of the Metro fixed payload identifies FixedPage parts as part of a FixedDocument. The content type of the FixedDocument part is defined in Appendix H, “Standard Namespaces and Content Types.” The element contains an ordered sequence of pages as a single multi-page document.
is the only allowable child element of the element. The elements MUST be in sequential markup order matching the page order of the document.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
7.5.2.1
7.5 Document Markup
83
PageContent Element
element PageContent diagram
attributes Name
Type
Use
Source
xs:anyURI
required
Default
Fixed
Annotation
Width
ST_GEOne
Typical width of pages contained in the
Height
ST_GEOne
Typical height of pages contained in the
A URI string that refers to the page content, held in a distinct part within the package. The content identified MUST be a part within the package.
annotation Defines a reference from a to a part containing a element
Each element refers to the source of the content for a single page. To determine the number of pages in the document, count the number of children contained within the .
has a single required attribute, Source, which refers to the FixedPage part for the contents of a page. has only one allowable child element, , and MUST NOT contain more than a single child. may optionally include an advisory Height and Width attribute reflecting the size of a single page. The authoritative Height and Width are specified in the FixedPage part. The Height and Width attributes allow applications such as viewers to make visual layout estimates for content quickly, without loading and parsing all of the individual FixedPage parts.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 84
7.5 Document Markup
7.5.2.2
Metro Specification and Reference Guide
PageContent.LinkTargets Element
element PageContent.LinkTargets diagram
annotation Contains a collection of LinkTarget elements, each of which is addressable via hyperlink.
The element defines the list of elements that specify each named element on the given page that may be addressed by hyperlinks (e.g., from FixedPage.NavigateUri attributes). For example, in the following markup, the page named “FixedPage2” contains two elements with Name attribute values of “Anchor1” and “Anchor2” respectively.
7.5.2.3
LinkTarget Element
element LinkTarget diagram
attributes Name Name
Type
Use
ST_Name required
Default
Fixed
Annotation Name contains a string value that is used to identify the current element as a named, addressable point in the document for purposes of hyperlinking into the current document.
annotation Specifies a hyperlink-addressable point on the related page.
The element identifies a specific Name that exists on the FixedPage corresponding to its enclosing element. This Name corresponds to the Name of another element on the FixedPage. By duplicating this information in the FixedDocument part, the reader application does not
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
7.5 Document Markup
85
need to load every FixedPage part to determine if a particular Name exists in the document. For more
information, see Section 6.2.2, “Hyperlinks” on page 70 and Section 11.3, “Hyperlink Attributes” on page 192.
7.5.3
FixedPage Element
element FixedPage diagram
attributes Name
Version 0.7
Type
Use
Width
ST_GEOne
required
Default
Fixed
Annotation MUST be greater than or equal to 1 (real number value in 1/96 of an inch)
Height
ST_GEOne
required
MUST be greater than or equal to 1 (real number value in 1/96 of an inch)
ContentBox
ST_ContentBox
BleedBox
ST_BleedBox
Specifies which area of the page contains imageable content that must be fit on the imageable area when printing or viewing. RECOMMENDED. List of four coordinate values (Left,Top,Right,Bottom), expressed as real numbers and separated by commas. If omitted, the ContentBox default is (0,0,W idth,Height), but may be inferred from the actual page contents.
Specifies the area which includes
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 86
7.5 Document Markup
Metro Specification and Reference Guide
printing-related crop-marks that may be outside of the physical page. List of four coordinate values (Left,Top,Right,Bottom), expressed as real numbers and separated by commas. If omitted, the BleedBox default is (0,0,W idth,Height).
RenderTransform
ST_Matrix
xml:lang
Name
RenderTransform establishes a new coordinate frame for the child elements of the FixedPage, such as a canvas. The attributes ‘BleedBox’, ‘ContentBox’, ‘W idth’ and ‘Height’ are not affected by RenderTransform. required
ST_Name
This attribute specifies the default language used for any child element contained within the current element or nested child elements. The language is specified according to IETF RFC 3066.
Name contains a string value that is used to identify the current element as a named, addressable point in the document for purposes of hyperlinking into the current document.
annotation Each FixedPage part contains FixedPage markup describing the rendering of a single page of content.
Each FixedPage part represents the contents of a page in a single element with and elements, optionally using elements to group them. The and elements are together the base for all marks rendered on a FixedPage. The FixedPage part MAY specify a version-control mechanism. If versioning markup is used, the part must include a reference to the versioning namespace. For more information, see Chapter 4, “Versioning and Extensibility”. The following terminology and technologies are used to describe page sizes within Reach packages. •
Producer media size . The producer media size represents the media size that is used by the content producer for layout. This size is described by the Height and Width attributes of the .
•
Producer bleed size . The producer bleed size represents the overflow (or “bleed”) box used by a content producer for registration and layout. This size is described by the BleedBox attribute of the . If the BleedBox attribute is omitted, then the producer bleed size is defined
•
Producer content size . The producer content size represents the content bounding box specified by the content producer. This size is described by the ContentBox attribute of the . If the ContentBox attribute is omitted, then the producer content size is defined as the producer media size.
as the producer media size.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
•
7.5 Document Markup
87
Physical media size . The physical media size represents the physical media on which the content
will be printed. This size is described by the PageMediaSize keyword in the Print Schema. The PageMediaSize is page-orientation agnostic. This means that the representation of physical media size is defined by two dimensions: PageMediaSizeX and PageMediaSizeY, where PageMediaSizeX ≤ PageMediaSizeY. For more information, see Section 1.1.16.1, “Print Schema Keywords” on page 4.
•
Physical imagable size . The physical imageable size represents the area printable by a specific
print device. This size is described by the PageImageableSize keyword in the Print Schema. The PageImageableSize is relative to the physical media size (PageMediaSize keyword) and the orientation (PageOrientation keyword). For more information, see Section 1.1.16.1, “Print Schema Keywords” on page 4.
A FixedPage part MUST have Height and Width attributes specified, and MUST have the xml:lang attribute specified. It is RECOMMENDED that a ContentBox be specified for the FixedPage part. Figure 7–1.
Width Origin (0,0)
Text ContentBox
Height Application Media Size
BleedBox
Text
When rendering a FixedPage for printing, the consumer MUST be aware of the interaction between the FixedPage markup and the PrintTicket. The interaction for media scaling is governed by the PageMediaSize, PageImageableSize and the PageScaling Print Schema keywords. Table 7–1 describes the behavior of specific PageScaling options that influence the rendering of the FixedPage. The table does not represent an exhaustive list of PageScaling options. For more information, see Section 1.1.16.1, “Print Schema Keywords” on page 4.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 88
7.5 Document Markup
Metro Specification and Reference Guide
Table 7–1.
PageScaling Option
Behavior
FitApplicationBleedSizeToPageImage ableSize
Consumer MUST scale the BleedBox (producer bleed size) to the PageImageableSize preserving the Aspect Ratio. See the Print Schema PageScaling definition. For more information, see Section 1.1.16.1, “Print Schema Keywords” on page 4. PageMediaSize BleedBox PageImageableSize
FixedPage ContentBox
FitApplicationContentSizeToPage ImageableSize
Version 0.7
Consumer MUST scale the ContentBox (producer content size) to the PageImageableSize preserving the Aspect Ratio. See the Print Schema PageScaling definition. For more information, see Section 1.1.16.1, “Print Schema Keywords” on page 4.
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
7.5 Document Markup
89
PageScaling Option
Behavior
FitApplicationMediaSizeToPage ImageableSize
Consumer MUST scale the Height and Width (producer media size) to the PageImageableSize preserving the Aspect Ratio. See the Print Schema PageScaling definition. For more information, see Section 1.1.16.1, “Print Schema Keywords” on page 4.
FitApplicationMediaSizeToPageMedia Size
Consumer MUST scale the Height and Width (producer media size) to the PageMediaSize preserving the Aspect Ratio. See the Print Schema PageScaling definition. For more information, see Section 1.1.16.1, “Print Schema Keywords” on page 4.
The element is used in the sample markup below.
7.5.3.2
BleedBox Attribute
The BleedBox attribute specifies the area which includes printing-related crop-marks that may be outside of the physical page. The BleedBox property value is expressed as four real number coordinate values (Left, Top, Right, Bottom) separated by commas (additional whitespace MAY appear). These values are specified in units of 1/96", and the BleedBox is not affected by any render transformation of the FixedPage.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 90
7.5 Document Markup
Metro Specification and Reference Guide
BleedBox values that do not satisfy the following conditions are invalid and SHOULD NOT be rendered (Metro consumers SHOULD generate an error condition instead): •
The BleedBox Left value MUST be less than or equal to the ContentBox Left value
•
The BleedBox Top value MUST be less than or equal to the ContentBox Top value
•
The BleedBox Right value MUST be greater than or equal to the ContentBox Right value
•
The BleedBox Bottom value MUST be greater than or equal to the ContentBox Bottom value
If this attribute is omitted, the BleedBox default is (0,0,Width,Height). 7.5.3.3
ContentBox Attribute
The ContentBox attribute specifies which area of the page contains imageable content that must be fit on the imageable area when printing or viewing. Specifying this attribute is RECOMMENDED. The ContentBox property value is expressed as four real number coordinate values (Left, Top, Right, Bottom), expressed as real numbers and separated by commas (additional whitespace characters MAY appear). These values are specified in units of 1/96", and the ContentBox is not affected by any render transformation of the FixedPage. ContentBox values that do not satisfy the conditions listed above are invalid and SHOULD NOT be rendered (Metro consumers SHOULD generate an error condition instead): •
The ContentBox Left value MUST be greater than or equal to 0 and less than the ContentBox Right value
•
The ContentBox Top value MUST be greater than or equal to 0 and less than the ContentBox Bottom value
•
The ContentBox Right value MUST be less than or equal to the Width attribute
•
The ContentBox Bottom value MUST be less than or equal to the Height attribute
If this attribute is omitted, the default is (0,0,Width,Height), but MAY be inferred from the actual page contents.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
7.6
7.6 Page Markup
91
Page Markup
Reach markup includes two elements that provide page marking (the and elements) and one element that groups child elements (the element).
The and elements specify brush properties that describe how the elements are painted to produce page markings. Some properties of , , and elements are composable, meaning that the page
marking effect is determined by a combination of the property of the element property and all of the properties of its ancestor elements. For example, the effective transparency of an element is determined by inspecting the Opacity and OpacityMask properties of the element itself as well as the Opacity and OpacityMask properties of all its ancestor elements. A element with an Opacity value of 0.5 nested inside a element with an Opacity value of 0.5 results in an effective 25% opacity of the element when rendered. The coordinate space used to render page marking elements is also composable. Elements are rendered by default in a coordinate space with units of 1/96". By applying an affine matrix transformation to an element or its ancestors with the Transform or RenderTransform properties, the effective coordinate space for any particular element can be adjusted.
7.6.1
Canvas Element
element Canvas diagram
attributes Name
Version 0.7
Type
Use
Final
Default
Fixed
Annotation
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 92
7.6 Page Markup
Metro Specification and Reference Guide
RenderTransform
ST_RscRefMatrix
Clip
ST_RscRefAbbrGeom
Opacity
ST_ZeroOne
OpacityMask
ST_RscRef
Specifies a mask of alpha values (using only the alpha channel of a brush) that is applied to the canvas in the same fashion as the Opacity attribute, but allows different alpha value for different areas of the element.
Name
ST_Name
Name contains a string value that is used to identify the current element as a named, addressable point in the document for purposes of hyperlinking into the current document.
FixedPage.NavigateUri
xs:anyURI
The FixedPage.NavigateUri attribute is used to associate a hyperlink URI with the element. This may be a relative or absolute URI addressing a resource external or internal to the package.
RenderTransform establishes a new coordinate frame for the child elements of the canvas, such as another canvas. RenderTransform also affects ‘Clip’ and ‘OpacityMask’.
xml:lang
Version 0.7
Limits the rendered region of the element. 1.0
Defines uniform transparency of the canvas. The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values outside of this inclusive range are invalid.
This attribute specifies the default language used for any child element contained within the current element or nested child elements. The language is specified according to IETF RFC 3066.
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
7.6 Page Markup
x:Key
93
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified.
annotation The element is used to group FixedPage elements together.
The element is used to group elements together. For example, and elements can be grouped together in a when they share a composed common attribute (i.e., Opacity, Clip, RenderTransform, or OpacityMask). By grouping these elements together within a
, common attributes can often be applied to the instead of to the individual elements. For details on the Clip, FixedPage.NavigateUri, Name, Opacity, OpacityMask, RenderTransform, and Resources properties, see Chapter 11, “Shared Element Attributes”. The following markup example illustrates the use of .
7.6.2
Path Element
The element specifies a geometry that may be filled with a brush. For more information, see Section 8.1, “Path Element” on page 95.
7.6.3
Glyphs Element
The element is used to represent a run of text, all from the same font. The element provides information for accurate rendering, as well as supporting search and selection features in Reach viewers. For more information, see Section 9.1, “Glyphs Element” on page 131.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
95
Chapter 8. Graphics 8.1
Path Element
element Path diagram
attributes Name Data
Version 0.7
Type
Use
ST_RscRefAbbrGeom
Final
Default
Fixed
Annotation Describes the geometry of
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 96
8.1 Path Element
Metro Specification and Reference Guide
the path.
Version 0.7
Fill
ST_RscRefColor
FillRule
ST_FillRule
RenderTransform
ST_RscRefMatrix
Clip
ST_RscRefAbbrGeom
Opacity
ST_ZeroOne
OpacityMask
ST_RscRef
Describes the brush used to paint the geometry specified by the element’s Data property.
EvenOdd
The FillRule attribute specifies how the intersecting areas of geometric shapes are combined to form a region. Valid values are ‘EvenOdd’ and ‘NonZero’. The FillRule attribute is only used if Path.Data contains a PathGeometry as immediate child element, or Path.Data is specified using the abbreviated geometry syntax. If Path.Data contains a GeometryGroup or a CombinedGeometry, the geometry is not affected by Path.FillRule.
RenderTransform establishes a new coordinate frame for all attributes of the path and for all child elements of the path, such as the geometry defined by Path.Data.
Limits the rendered region of the element. 1.0
Defines uniform transparency of the path element. The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values outside of this inclusive range are invalid.
Specifies a mask of alpha values (using only the alpha channel of a brush) that is applied to the path in the
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.1 Path Element
97
same fashion as the Opacity attribute, but allows different alpha value for different areas of the element.
Version 0.7
Stroke
ST_RscRefColor
Specifes a brush used to draw the stroke.
StrokeDashArray
ST_EvenArray
Specifies the length of dashes and gaps of the outline stroke. These values are specified as multiples of the stroke thickness as a space separated list with an even number of values. When a stroke is drawn, the dashes and gaps specified by these values are repeated to cover the length of the stroke. If this attribute is omitted, the stroke is drawn solid, without any gaps. Negative values are treated as absolute.
StrokeDashCap
ST_DashCap
Flat
A value specifying how the ends of each dash are drawn. Valid values are ‘Flat’, ‘Round’, ‘Triangle’.
StrokeDashOffset
xs:double
0.0
A value that adjusts the start point for repeating the dash array pattern. If this value is omitted, the dash array aligns with the origin of the stroke. Values are specified as multiples of the stroke thickness.
StrokeEndLineCap
ST_LineCap
Flat
This value defines the shape of the end of the last dash in a stroke. Valid values are ‘Flat’, ‘Square’, ‘Round’, ‘Triangle’.
StrokeStartLineCap
ST_LineCap
Flat
This value defines the shape of the beginning of the first dash in a stroke. Valid values are ‘Flat’, ‘Square’, ‘Round’, ‘Triangle’.
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 98
8.1 Path Element
Version 0.7
Metro Specification and Reference Guide
StrokeLineJoin
ST_LineJoin
Miter
Specifies how a stroke is drawn at a corner of a Path. Valid values are ‘Miter’, ‘Bevel’, ‘Round’. If ‘Miter’ is selected, the ‘StrokeMiterLimit’ value is used in drawing the stroke.
StrokeMiterLimit
ST_GEOne
10.0
The ratio between maximum miter length and stroke thickness. This value MUST be equal to or greater than 1.0. The value of StrokeMiterLimit is only significant if StrokeLineJoin specifies ‘Miter’.
StrokeThickness
ST_GEZero
1.0
Specifies the thickness of a stroke, in 1/96s of an inch, modified by the transformations currently in effect, including the Path's RenderTransform. The stroke is drawn on top of the boundary of the geometry specified by the element’s ‘Data’ property. Half of the StrokeThickness extends to the outside of the geometry specified by the element’s ‘Data’ property and the other half extends to the inside of the geometry.
Name
ST_Name
Name contains a string value that is used to identify the current element as a named, addressable point in the document for purposes of hyperlinking into the current document.
FixedPage.NavigateUri
xs:anyURI
The FixedPage.NavigateUri attribute is used to associate a hyperlink URI with the element. This may be a relative or absolute URI addressing a resource external or internal to the package.
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.1 Path Element
99
xml:lang
This attribute specifies the default language used for any child element contained within the current element or nested child elements. The language is specified according to IETF RFC 3066.
x:Key
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified.
annotation The element is the definition of a single graphical effect to be rendered to the page. It paints a geometry with a brush and draws a stroke around it.
The element is the sole means of adding vector graphics and images to a . The element is the definition of a single graphical effect to be rendered to the page. The Data property of the element describes a geometric description of the area on which to apply a given effect. This geometry can be described verbosely under the element using the elements described in Section 8.2, “Geometries and Figures” on page 104, or it can be described in an abbreviated fashion directly in the Data attribute of . For more information, see Section 8.2.3, “Abbreviated Geometry Syntax” on page 126. The FillRule attribute describes the algorithm used to consider which internal areas are included in the geometry described by the Data property. For more information, see Section 8.1.2, “FillRule Attributes” on page 101. The child element is used to describe the appearance of the areas defined by the Data property and FillRule attribute. It contains a element (see Chapter 10, “Brushes”) that is used to fill the described areas. These can include a solid color, an image, a gradient, or a vector drawing pattern. The child element is then used to describe the appearance of the borders of the areas defined by the Data property and FillRule attribute. It also contains a element, which is used to fill the borders according to the stroke properties (e.g., StrokeThickness). The transparency of the rendered element is controlled by the Opacity attribute. More complex transparency descriptions may be defined using the OpacityMask attribute to control the transparency of the described by the Fill property. Finally, the rendering may be cropped by specifying a clipping region in the Clip property, which contains a geometry description of the clipping area. See Section 8.2.1, “Geometries” on page 104 for how geometries are defined.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 100
8.1 Path Element
Metro Specification and Reference Guide
For details on the Clip, FixedPage.NavigateUri, Name, Opacity, OpacityMask, and RenderTransform properties, see Chapter 11, “Shared Element Attributes”.
8.1.1
Path.Data Element
element Path.Data diagram
annotation Describes the path’s geometry.
The element describes the geometric area of a Path. It contains a single geometry (see Section 8.2, “Geometries and Figures” on page 104). Example markup is included below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.1 Path Element
101
This markup produces the following: Figure 8–1.
8.1.2
FillRule Attributes
The fillable area of a geometry is defined by taking all of the contained PathFigures and applying the FillRule to determine the enclosed area. FillRule options specify how the intersecting areas of geometric shapes are combined to form a region. Wherever the FillRule attribute appears on elements in a nested structure, the parent attribute always takes precedence. The FillRule attribute appears on the following elements:
•
•
•
EvenOdd Fill Algorithm This rule determines the “insideness” of a point on the canvas by drawing a ray from that point to infinity in any direction and counting the number of segments from the given shape that the ray crosses. If this number is odd, the point is inside; if even, the point is outside. This is the default rule used throughout Reach markup. Figure 8–2. Fill Using EvenOdd Algorithm.
NonZero Fill Algorithm This rule determines the “insideness” of a point on the canvas by drawing a ray from that point to infinity in any direction and then examining the places where a segment of the shape crosses the ray. Starting with a count of zero, add one each time a segment crosses the ray from left to right and subtract one
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 102
8.1 Path Element
Metro Specification and Reference Guide
each time a path segment crosses the ray from right to left. After counting the crossings, if the result is zero then the point is outside the path. Otherwise, it is inside. Figure 8–3. Fill Using NonZero Algorithm.
8.1.3
Path.Fill Element
element Path.Fill diagram
annotation Describes the brush used to paint the geometry specified by the element’s Data property.
The element specifies the Brush (see Chapter 10, “Brushes”) that is used to fill the region described in the element. Example markup is shown below, filling a geometry with a solid color:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.1 Path Element
103
This markup produces the following result: Figure 8–4.
8.1.4
Path.Stroke Element
element Path.Stroke diagram
annotation Specifies a brush used to draw the stroke.
The Stroke property of the Path specifies the appearance of the border of the geometry specified by the Data property of the Path. It is filled with a element. Only those segments of the under the element that set the IsStroked attribute to “true” (the default value if omitted) are stroked. A that does not include a element will not stroke that segment. The following is an example of the element using a gradient brush to fill the thick border of a box:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 104
8.2 Geometries and Figures
Metro Specification and Reference Guide
This markup produces the following results: Figure 8–5.
For more information on stroke rendering, see •
Section 13.1.14, “Rules for Dash Cap Rendering” on page 241.
•
Section 13.1.16, “Rules for Line Cap Rendering” on page 245.
8.2
Geometries and Figures
Geometries are used in FixedPage markup to build visual representations of geometric shapes. The smallest atomic unit in a geometry is a segment. Segments may be lines, curves, or define start positions, or close behavior. These segments are combined into a definition, consisting of a , one or more line or curve middle segments, and an OPTIONAL . One or more elements are grouped together to define a , which is the smallest geometric unit. A MAY define the fill algorithm to be used on the component elements. Two individual geometry elements may be combined together for rendering and clipping, according to specified Boolean fill operations, using the element. Finally, a collection of geometry elements may be grouped together using a element. A single , , or may be used in the Data property of the Path to describe the overall geometry of the element.
8.2.1
Geometries
There are three elements considered to be a complete geometry definition:
•
•
•
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2.1.1
8.2 Geometries and Figures
105
GeometryGroup
element GeometryGroup diagram
attributes Name
Type
FillRule
ST_FillRule
Transform
ST_RscRefMatrix
Use
Default EvenOdd
Fixed
Annotation FillRule options specify how the intersecting areas of geometric shapes contained in this GeometryGroup are combined to form a region. Valid values are ‘EvenOdd’ and ‘NonZero’. If the current GeometryGroup is embedded in another GeometryGroup, the FillRule attribute is ignored, and instead the FillRule attribute of the outermost containing GeometryGroup is applied.
Specifies a local transformation matrix that is applied to the all children of the GeometryGroup before it is used for filling, clipping or stroking.
x:Key
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified.
annotation Defines a collection of geometries to be treated as a single geometry.
A is a collection of , , and elements. It is interpreted as a single constructed from the elements of all its children. This element provides a simple mechanism to construct a complex geometry from simpler geometries
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 106
8.2 Geometries and Figures
Metro Specification and Reference Guide
The FillRule attribute is ignored when the element is a child element of another geometry. See Section 8.1.2, “FillRule Attributes” on page 101 for more details. Example markup is shown below:
This markup produces the following results: Figure 8–6.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2.1.2
8.2 Geometries and Figures
107
CombinedGeometry
element CombinedGeometry diagram
attributes Name
Type
Use
CombineMode
ST_CombineMode
required
Geometry1
ST_RscRefAbbrGeom
Specifies the first geometry operand to be combined.
Geometry2
ST_RscRefAbbrGeom
Specifies the second geometry operand to be combined.
Transform
ST_RscRefMatrix
Specifies a local transformation matrix that is applied to the all children of the CombinedGeometry before it is used for filling, clipping or stroking.
x:Key
Default
Fixed
Annotation Specifies a binary combination mode for the child Geometry elements. Valid values are ‘Xor’, ‘Union’, ‘Intersect’, and ‘Exclude’.
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified.
annotation A set of PathGeometry, GeometryGroup, or CombinedGeometry elements rendered using Boolean CombineMode operations.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 108
8.2 Geometries and Figures
Metro Specification and Reference Guide
A combines two individual geometry elements (, , or ) into a single geometry, according to a Boolean operation specified by the CombineMode attribute. The resulting behavior is: •
The geometry is constructed from the filled area of its Geometry1 and Geometry2 attributes. Segments in the component elements that do not contribute to the boundary of the filled area are omitted from the .
•
The geometry MAY replace curve segments in its items with their polygonal approximation.
•
The geometry reorganizes its combined boundary into loops that do not cross each other or themselves. For example, a single loop that is shaped like the figure-eight is broken into two simple teardrop-shaped loops.
•
All edges are stroked in the resulting geometry.
Example markup is shown below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2 Geometries and Figures
109
This markup produces the following results: Figure 8–7.
8.2.1.2.2
CombineMode Attribute
Table 8–1. CombineMode
Result
Exclude
The set of all points that are in Geometry1 (the left diamond) but not in Geometry2 (the right diamond)
Intersect
The set of all points that are contained within Geometry1 (the left diamond) and Geometry2 (the right diamond)
Union
The set of all points that are contained within Geometry1 (the left diamond) or Geometry2 (the right diamond) or both
Xor
The set of all points that are contained within Geometry1 (the left diamond) or Geometry2 (the right diamond) but not both
Version 0.7
Diagram
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 110
8.2 Geometries and Figures
8.2.1.2.3
Metro Specification and Reference Guide
Geometry1 and Geometry2 Properties
The Geometry1 and Geometry2 properties are each a single geometry that can be expressed as a property element (i.e., ), as a resource reference, or as a property attribute of the element using the abbreviated geometry syntax described in Section 8.2.3, “Abbreviated Geometry Syntax” on page 126. element CombinedGeometry.Geometry1 diagram
annotation Specifies the first geometry operand to be combined.
element CombinedGeometry.Geometry2 diagram
annotation Specifies the second geometry operand to be combined.
The following is an example of the abbreviated syntax for expressing a CombinedGeometry (for more information, see Section 8.2.3, “Abbreviated Geometry Syntax” on page 126):
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2.1.3
8.2 Geometries and Figures
111
PathGeometry
element PathGeometry diagram
attributes Name
Type
FillRule
ST_FillRule
Transform
ST_RscRefMatrix
Use
Default
Fixed
EvenOdd
Annotation This attribute has no effect and will be deprecated. Do not use. (FillRule options specify how the intersecting areas of geometric shapes are combined to form a region. Valid values are ‘EvenOdd’ and ‘NonZero’. If the current element is embedded in a CombinedGeometry, the FillRule attribute is ignored.)
Specifies a local transformation matrix that is applied to the all children of the PathGeometry before it is used for filling, clipping or stroking.
x:Key
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified.
annotation Set of PathFigure elements.
A element contains a set of elements. The union of the elements defines the interior of the according to the FillRule attribute (see Section 8.1.2, “FillRule Attributes” on page 101). Example markup is shown below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 112
8.2 Geometries and Figures
Metro Specification and Reference Guide
This markup produces the following results: Figure 8–8.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2.2
8.2 Geometries and Figures
113
Figures
8.2.2.1
PathFigure
element PathFigure diagram
annotation Specifies a set of one or more segment elements defining a closed region.
A element is composed of a set of one or more line or curve segments. The segment elements define the shape of the . The first child segment MUST be a element, followed by one or more middle segments, and an OPTIONAL element. Middle segment elements include:
•
•
•
•
•
•
•
Line segments and curve segments SHOULD NOT be specified with zero-length. If they are specified as zero-length, then nothing is drawn, even if line caps would normally be visible.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 114
8.2 Geometries and Figures
8.2.2.2
Metro Specification and Reference Guide
StartSegment Element
element StartSegment diagram
attributes Name Point
Type
Use
Default
Fixed
ST_Point required
Annotation The coordinates of the line segment (starting point). Values separated by commas, although additional whitespace may appear.
annotation The first segment of a PathFigure.
The element defines the starting point for the drawing, relative to the local effective coordinate space. 8.2.2.3
Middle Segment – ArcSegment
element ArcSegment diagram
attributes Name
Version 0.7
Type
Use
Point
ST_Point
required
Default
Fixed
Specifies the endpoint of the elliptical arc.
Size
ST_Point
required
Specifies the x- and y-radius of the elliptical arc as an X,Y pair.
XRotation
xs:double
required
Specifies a value that indicates how the ellipse is rotated relative to the current coordinate system.
Final
Annotation
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2 Geometries and Figures
115
LargeArc
ST_Boolean required
Specifies a Boolean that determines whether the arc is drawn with a sweep of 180 degrees or greater.
SweepFlag
ST_Boolean required
Specifies a Boolean that determines whether the arc is drawn in a positive-angle or negative-angle direction.
IsStroked
ST_Boolean
true
Specifies whether the stroke for this segment of the path is drawn. Can be ‘true’ or ‘false’.
annotation Represents an elliptical arc between two points.
The element describes an elliptical arc. It is geometrically defined by the intersection of two ellipses that have the same x-radius and y-radius. The ellipses intersect at the starting and ending points of the arc. An is defined as follows: Table 8–2. Starting Point
Implicitly defined by the previous point in the definition.
Ending Point
Specified by the Point attribute.
Arc Size
Defined by the Size attribute. This value consists of the comma-delimited X and Y radii of the ellipses that will be used to define the arc, e.g., 100,50.
Rotation
Specified by the XRotation attribute, this determines how the ellipses defining the arc are rotated with respect to the X-axis, in degrees. Positive values are clockwise and negative values are counter-clockwise.
Large Arc Flag
Specified by the LargeArc attribute, this flag indicates which of the arc pairs created by the intersecting ellipses to use. When the flag is true, it uses the larger arc (arc length >= 180 degrees), and when it is false it uses the smaller arcs (arc length < 180 degrees).
Sweep Flag
Specified by the SweepFlag attribute, this flag determines which of the two possible arcs (selected by the Large Arc Flag) is used. Beginning at the Starting Point, one arc proceeds in the positive (clockwise) direction, while the other proceeds in the negative (counter-clockwise) direction. If the Sweep Flag is true, the clockwise arc is selected; otherwise the counter-clockwise arc is selected.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 116
8.2 Geometries and Figures
Metro Specification and Reference Guide
Below are illustrations of how the Large Arc Flag and Sweep Flag combine to select a specific arc: Figure 8–9.
An example of the markup is shown below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2 Geometries and Figures
117
This markup generates the following arc: Figure 8–10.
8.2.2.3.2
Out-of-Range Attributes
The following guidelines are followed when encountering nonsensical values for the various attributes: •
If the arc is impossible to render given the combination of radii specified in the Size attribute and the angle of rotation specified in the XRotation attribute, the ellipses are scaled equally until there is exactly one solution that satisfies the arc requirements to pass through the specified Point attribute.
•
If the Point attribute is the same as the previous point in the PathFigure, the segment is
•
If either the x- or y- radii in the Size attribute are zero, the segment is instead rendered as a with the same Point attribute.
•
If either the x- or y- radii in the Size attribute are negative, they are substituted with their
•
If the XRotation value is greater than 360, it is replaced by the value of the XRotation modulo
omitted.
absolute value.
360. If it is less than 0, it is replaced with a value normalized to the range 0 to 360.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 118
8.2 Geometries and Figures
8.2.2.4
Metro Specification and Reference Guide
Middle Segment – BezierSegment
element BezierSegment diagram
attributes Name
Type
Use
Point1
ST_Point
required
Default
Fixed
Annotation Specifies the first control point of the curve.
Point2
ST_Point
required
Specifies the second control point of the curve.
Point3
ST_Point
required
IsStroked
ST_Boolean
Specifies the end point of the curve. true
Specifies whether the stroke for this segment of the path is drawn. Can be ‘true’ or ‘false’.
annotation Represents a cubic Bezier curve drawn between two points.
The element describes a cubic Bézier curve. Bézier curves are drawn from the previous point in the and terminating at the point in the Point3 attribute. The tangents and curvature of the Bézier curve are controlled by the first two control points (Point1 and Point2 attributes). The Point1, Point2, and Point3 attributes each contain exactly one pair of commadelimited X,Y values. Example markup is shown below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2 Geometries and Figures
119
This markup generates the following curve: Figure 8–11.
8.2.2.5
Middle Segment – LineSegment
element LineSegment diagram
attributes Name
Type
Use
Point
ST_Point
required
IsStroked
ST_Boolean
Default
Fixed
Annotation The coordinates of the line segment (ending point). Values separated by commas, although additional whitespace may appear.
true
Specifies whether the stroke for this segment of the path is drawn. Can be ‘true’ or ‘false’.
annotation Represents a line between two points.
The element describes a straight line between the previous point in the to the point described in the Point attribute of the element. Example markup is shown below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 120
8.2 Geometries and Figures
Metro Specification and Reference Guide
This markup generates the following line: Figure 8–12.
8.2.2.6
Middle Segment – PolyBezierSegment
element PolyBezierSegment diagram
attributes Name
Type
Use
Points
ST_Points
required
IsStroked
ST_Boolean
Default
Fixed
Annotation Specifies control points of multiple Bezier segments. Coordinate values within each pair are separated by commas, although additional whitespace may appear. Coordinate pairs are separated from other coordinate pairs by whitespace.
true
Specifies whether the stroke for this segment of the path is drawn. Can be ‘true’ or ‘false’.
annotation A series of Bezier segments.
The describes a set of cubic Bézier curves. Bézier curves are drawn from the previous point in the or the previous Bézier curve in the segment and terminate at the third point (X3n,Y3n) in the Points attribute (where n is the curve being drawn). The tangents and curvature of each Bézier curve is controlled by the first two control points (X3n-2,Y 3n-2 and X3n-1,Y3n-1) in the Points attribute. The Points attribute contains a multiple of three whitespace-delimited pairs of comma-delimited X,Y values. Example markup is shown below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2 Geometries and Figures
121
This markup generates the following results: Figure 8–13.
8.2.2.7
Middle Segment – PolyLineSegment
element PolyLineSegment diagram
attributes Name
Type
Use
Points
ST_Points
required
IsStroked
ST_Boolean
Default
Fixed
Annotation A set of coordinates of the multiple segments that define the PolyLineSegment. Coordinate values within each pair are separated by commas, although additional whitespace may appear. Coordinate pairs are separated from other coordinate pairs by whitespace.
true
Specifies whether the stroke for this segment of the path is drawn. Can be ‘true’ or ‘false’.
annotation Specifies a set of points between which lines are drawn.
The element describes a polygonal drawing containing an arbitrary number of individual vertices. The Points attribute defines the vertices and contains whitespace-delimited pairs of comma-delimited X,Y values. Example markup is shown below:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 122
8.2 Geometries and Figures
Metro Specification and Reference Guide
This markup produces the following figure: Figure 8–14.
8.2.2.8
Middle Segment – PolyQuadraticBezierSegment
element PolyQuadraticBezierSegment diagram
attributes Name
Type
Use
Points
ST_Points
required
IsStroked
ST_Boolean
Default
Fixed
Annotation Specifies control points of multiple Quadratic Bezier segments. Coordinate values within each pair are separated by commas, although additional whitespace may appear. Coordinate pairs are separated from other coordinate pairs by whitespace.
true
Specifies whether the stroke for this segment of the path is drawn. Can be ‘true’ or ‘false’.
annotation A series of QuadraticBezierSegments.
The element describes a set of quadratic Bézier curves (see Section 8.2.2.9, “Middle Segment – QuadraticBezierSegment” on page 123) from the previous point in the
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2 Geometries and Figures
123
element through a set of vertices, using specified control points. The Points attribute
defines an off-curve control point (X2n-1,Y2n-1) followed by the end point (X2n,Y2n) for each quadratic Bézier curve (where n represents which quadratic Bézier curve). The Points attribute contains a multiple of two whitespace-delimited pairs of comma-delimited X,Y values. Example markup is shown below:
This markup produces the following curve: Figure 8–15.
8.2.2.9
Middle Segment – QuadraticBezierSegment
element QuadraticBezierSegment diagram
attributes Name
Version 0.7
Type
Use
Point1
ST_Point
required
Default
Fixed
The coordinates of the off-curve control point. Values separated by comma, although additional whitespace may appear.
Point2
ST_Point
required
The coordinates of the ending point. Values separated by comma, although additional whitespace may appear.
Final
Annotation
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 124
8.2 Geometries and Figures
IsStroked
ST_Boolean
Metro Specification and Reference Guide
true
Specifies whether the stroke for this segment of the path is drawn. Can be ‘true’ or ‘false’.
annotation Specifies a quadratic Bezier curve segment.
The element describes a quadratic Bézier curve from the previous point in the element to the specified end point using the specified control point. The Point1 attribute defines the control point (off the curve) and the Point2 attribute defines the end point, each as a pair of comma-delimited X,Y values. Example markup is shown below:
This markup produces the following curve: Figure 8–16.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2.2.10
8.2 Geometries and Figures
125
CloseSegment
element CloseSegment diagram
attributes Name IsStroked
Type ST_Boolean
Use
Default
Fixed
true
Annotation CloseSegment implies a last segment from the end of the last segment to the start point of the geometric shape specified in StartSegment. IsStroked specifies whether the stroke for this segment of the path is drawn. Can be ‘true’ or ‘false’.
annotation Optional last segment of a PathFigure. When specified, indicates a closed Path shape, connecting the last point to the first point of the shape. Used for stroking.
The element describes a straight line from the previous point in the element to the Point attribute of the child of element.
elements used in filled elements or in elements are implicitly closed. In the following markup example, the example shown previously includes a element:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 126
8.2 Geometries and Figures
Metro Specification and Reference Guide
This markup generates the following figure: Figure 8–17.
8.2.3
Abbreviated Geometry Syntax
The abbreviated geometry syntax MAY be used to specify a geometry of one or more figures comprised of multiple segments. Each figure specifies the segments with a Move command, draw commands, and an optional Close command. The following example demonstrates a simple Path, which is drawn using the abbreviated syntax:
A draw command can consist of the following commands (each producing segments in the figure): •
Line
•
Horizontal line
•
Vertical line
•
Cubic Bézier curve
•
Quadratic Bézier curve
•
Smooth cubic Bézier curve
•
Elliptical arc
Commands can be entered with an uppercase or a lowercase letter. Uppercase letters denote absolute values and lowercase letters denote relative values. When relative coordinate values are specified, each coordinate pair expresses a relative offset to the current endpoint (the previous command's terminating coordinate pair). If a relative value is used for the required first Move (m) command, the current endpoint is (0,0) by definition. If a relative value is used following a Close command (Z or z), the current endpoint is the first point of the previous figure. If entering more than one command of the same type sequentially, the duplicate command entry MAY be omitted; for example, “L 100,200 300,400” is equivalent to “L 100,200 L 300,400”. The current endpoint is still determined as though each command appeared individually. The syntax of commands is a single letter (uppercase for absolute, lowercase for relative) followed by one space character, followed by each parameter of the command, space-delimited. Points are specified as a comma-delimited pair with no spaces, e.g. "10,10".
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2 Geometries and Figures
127
Table 8–3. Move Command and Draw Commands. Command
Syntax
Description
Move
M x,y
Establishes a new current endpoint. Every geometry MUST begin with a Move command. Each figure MUST also begin with a Move command; subsequent Move commands indicate the start of a new figure.
or
m x,y
Line
L x,y
Draws a straight line from the current point to the specified point.
or
l x,y Horizontal Line
L 20,30 is a valid Line command.
H x
Draws a horizontal line from the current endpoint to the specified x-coordinate.
or
h x
H 90 is a valid Horizontal Line command.
Vertical Line
V y
Draws a vertical line from the current endpoint to the specified y-coordinate.
or
v y Cubic Bézier Curve
v 90 is a valid Vertical Line command.
C x1,y1 x2,y2 x3,y3 or
c x1,y1 x2,y2 x3,y3
Draws a cubic Bézier curve from the current endpoint to the specified point (x3,y3) using the two specified control points (x1,y1 and x2,y2); the first control point determines the initial direction (tangent) of the curve, and the second control point determines the terminating direction (tangent) of the curve.
C 100,200 200,400 300,200 is a valid Cubic Bézier Curve command. Quadratic Bézier Curve
Q x1,y1 x2,y2
Draws a quadratic Bézier curve from the current endpoint to the specified point (x2,y2) using the specified control point (x1,y1).
or
q x1,y1 x2,y2
q 100,200 300,200 is a valid Quadratic Bézier Curve command.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 128
8.2 Geometries and Figures
Metro Specification and Reference Guide
Command
Syntax
Description
Smooth Cubic Bézier Curve
S x1,y1 x2,y2
Draws a cubic Bézier curve from the current endpoint to the specified point (x2,y2). The first control point is
or
s x1,y1 x2,y2
assumed to be the reflection of the second control point of the previous command, relative to the current endpoint. If there is no previous command or if the previous command was not a Cubic Bézier Curve command or Smooth Cubic Bézier Curve command, the first control point is assumed to be coincident with the current endpoint. The second control point is specified by x1,y1.
S 100,200 200,300 is a valid Smooth Cubic Bézier Curve command. Elliptical Arc
A xr,yr rx flag1 flag2 x,y or
a xr,yr rx flag1 flag2 x,y
Draws an elliptical arc from the current endpoint to the specified point (x,y). The size and orientation of the ellipse are defined by xr , yr, and rx. xr defines the x-radius, yr defines the y-radius, and rx defines the x-axis rotation in degrees, which indicates how the ellipse is rotated relative to the current coordinate system. The center of the ellipse is calculated automatically. In most situations, four different arcs satisfy the specified constraints. flag1 and flag2 indicate which arc to use. Of the four candidate arc sweeps, two represent large arcs with sweeps of 180 degrees or greater, and two represent smaller arcs with sweeps less than 180 degrees. If flag1 is 1, one of the two larger arc sweeps is chosen. If flag1 is 0, one of the smaller arc sweeps is chosen. No other values of flag1 are valid. If flag2 is 1, the arc is drawn in a positive-angle (clockwise) direction. If flag2 is 0, the arc is drawn in a negative-angle (counter-clockwise) direction. No other values of flag2 are valid .
a 200,70 10 0 1 100,100 is a valid elliptical arc command.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
8.2 Geometries and Figures
129
Command
Syntax
Description
Close
Z or z
Draws a straight line from the current endpoint to the first point of the current figure and then ends the figure.
If the next command after a Close command is a Move command, the Move command specifies the initial point of the next figure. Otherwise, the next figure starts at the same initial point as the current figure.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
131
Chapter 9. Text 9.1
Glyphs Element
element Glyphs diagram
attributes Name BidiLevel
Version 0.7
Type
Use
xs:integer
Default 0
Final
Fixed
Annotation The Unicode algorithm bidirectional nesting level. Numerically even values imply left-to-right layout, numerically odd values imply right-to-
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 132
9.1 Glyphs Element
Metro Specification and Reference Guide
left layout. Right-to-left layout places the run origin at the right side of the first glyph, with positive advance widths (representing advances to the left) placing subsequent glyphs to the left of the previous glyph.
CaretStops
ST_CaretStops
Identifies the positions within the sequence of 'UnicodeString' characters at which a text-selection tool may place a text-editing caret. Potential caret-stop positions are identified by their indices into the UTF16 code units represented by the 'UnicodeString'. When this attribute is missing, this element MUST be interpreted as having a caret stop between every Unicode UTF-16 code unit. The 'CaretStop' value SHOULD indicate that the caret may not in stop front of most combining marks or in front of the second UTF-16 code unit of UTF16 surrogate pairs.
DeviceFontID
xs:string
Specifies an identifier uniquely identifying a specific device font. The identifier is typically defined by a hardware vendor or font vendor.
Fill
ST_RscRefColor
FontRenderingEmSize
ST_GEZero
required
Font size in drawing surface units (measured as a float in 1/96th of an inch, in the absence of a transform). This value MUST be greater than or equal to 0. A value of 0 results in no visible text.
FontUri
xs:anyURI
required
The URI of the physical font from which all glyphs in this run are drawn. The URI MUST be internal, referencing a font contained in the package. If the physical font referenced is a TrueType Collection (containing multiple font faces), the fragment portion of the URI indicates which font face should be used (i.e.,
Version 0.7
Describes the brush used to fill the shape of the rendered glyphs.
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
9.1 Glyphs Element
133
FontUri=”../Fonts/CJKSuper.TTC#0”).
OriginX
xs:double
required
X coordinate of first glyph in run, in 1/96ths of an inch (in the absence of a transform). The glyph is placed so that the leading edge of its advance vector and its baseline intersect with the point defined by the OriginX and OriginY attributes.
OriginY
xs:double
required
Y coordinate of first glyph in run, in 1/96ths of an inch (in the absence of a transform). The glyph is placed so that the leading edge of its advance vector and its baseline intersect with the point defined by the OriginX and OriginY attributes.
IsSideways
ST_Boolean
Indices
ST_Indices
A series of glyph indices and their attributes used for rendering this glyph run. If the UnicodeString specifies an empty String (“”), and the Indices attribute is missing, or also is empty (“”), no drawing occurs.
UnicodeString
ST_UnicodeString
Contains the string of text rendered by this element. The text is specified as Unicode code points.
StyleSimulations
ST_StyleSimulations
RenderTransform
ST_RscRefMatrix
Version 0.7
false
None
Flag indicating that a glyph is turned on its side, with the origin being defined as the top center of the unturned glyph.
Specifies style simulation. The possible simulations and their defined string values are ‘None’, ‘ItalicSimulation’, ‘BoldSimulation’, and 'BoldItalicSimulation'.
RenderTransform establishes a new coordinate frame for the glyph run specified by the element. Glyphs.RenderTransform affects Clip, OpacityMask, Fill, OriginX, OriginY, the actual shape of individual Glyphs, as well as the advance widths. Glyphs.RenderTransform also affects the font size and values specified in
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 134
9.1 Glyphs Element
Metro Specification and Reference Guide
the Indices attribute.
Clip
ST_RscRefAbbrGeom
Opacity
ST_ZeroOne
OpacityMask
ST_RscRef
Specifies a mask of alpha values (using only the alpha channel of a brush) that is applied to the glyphs in the same fashion as the Opacity attribute, but allows different alpha value for different areas of the element.
Name
ST_Name
Name contains a string value that is used to identify the current element as a named, addressable point in the document for purposes of hyperlinking into the current document.
FixedPage.NavigateUri
xs:anyURI
The FixedPage.NavigateUri attribute is used to associate a hyperlink URI with the element. This may be a relative or absolute URI addressing a resource external or internal to the package.
Limits the rendered region of the element. Only portions of the element that fall within the clip region, even partially clipped characters, produce marks on the page.
1.0
Defines uniform transparency of the glyph element. The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values outside of this inclusive range are invalid.
xml:lang
This attribute specifies the default language used for this Glyph element. The language is specified according to IETF RFC 3066.
x:Key
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
9.1 Glyphs Element
135
annotation The element is used to represent a run of text, all from the same font.
The element is used to represent a run of text of a single font. The element
provides information for accurate rendering, as well as supporting search and selection features in Reach viewers. For details on the Clip, FixedPage.NavigateUri, Name, Opacity, OpacityMask, and RenderTransform properties, see Chapter 11, “Shared Element Attributes”.
9.1.1
Glyphs Metrics
Each glyph defines metrics that specify how it aligns with other glyphs. The metrics are illustrated below. Figure 9–1.
Figure 9–2. Upright (Usually Horizontal) Glyph Metrics
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 136
9.1 Glyphs Element
Metro Specification and Reference Guide
Figure 9–3. Sideways (Usually Vertical) Glyph Metrics.
In general, glyphs within a font are either base glyphs or combining marks that may be attached to base glyphs. Base glyphs usually have an advance width that is non-zero, and a 0,0 offset vector. Combining marks usually have a zero advance width. The offset vector can be used to adjust the position of a combining mark and so may have a non-0,0 value for combining marks. Each glyph in the glyph run has three values controlling its position. The values indicate origin, advance width, and glyph offset. •
Origin. Each glyph is assumed to be given a nominal origin, for the first glyph in the run this is the origin of the run.
•
Advance Width. The advance width for each glyph provides the origin of the next glyph relative to the origin of this glyph. The advance vector is always drawn in the direction of the run progression.
•
Glyph Offset (Base or Mark). The glyph offset vector adjusts the position of this glyph relative to its nominal origin. The orientation of the glyph offset vector is not affected by the value of IsSideways.
9.1.2
Mapping Code Units to Glyphs
Typically, a UCS-4 code point in a UnicodeString will be represented by a single UTF-16 code unit and have a single corresponding glyph representation in the font. More complex mapping scenarios are common in non-Latin scripts: a single UCS-4 code point may map to two UTF-16 code units, multiple UTF16 code units may map to a single glyph, single UTF-16 code units may map to multiple glyphs based on context, and multiple UTF-16 code units may map indivisibly to multiple glyphs. In these cases, the clusters of UTF-16 code units are mapped using a cluster map. The cluster map contains one entry for each UTF-16 code unit in the UnicodeString. Each entry specifies the offset of the first glyph that represents the cluster of UTF-16 code units. The mapping between code unit(s) and glyph(s) has a default specification listed in the character mapping (cmap) table of the font. This information can be used to unambiguously specify the mappings in markup.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
9.1.2.1
9.1 Glyphs Element
137
One-to-One Mappings
When each UTF-16 code unit is represented by exactly one glyph, the cluster map entries are 0, 1, 2, ...
Figure 9–4. One-to-One Cluster Map.
9.1.2.2
Many-to-One Mappings
When two or more UTF-16 code units map to a single glyph, the entries for those UTF-16 code units specify the offset of that glyph in the glyph index buffer. In the following example, the ‘f’ and ‘i’ characters have been replaced by a ligature, as is common typesetting practice in many serif fonts. Figure 9–5. Many-to-One Cluster Map.
9.1.2.3
One-to-Many Mappings
When one UTF-16 code unit maps to two or more glyphs, the value in the ClusterMap for that UTF-16 code unit references the first glyph in the GlyphIndices array that represents that UTF-16 code unit. For example, the Thai “Sara Am” character contains a part that sits on top of the previous base character (the ring), and a part that sits to the right of the base character (the hook). When Thai text is microjustified, the hook is spaced apart from the base character, while the ring remains on top of the base character. Many fonts encode the ring and the hook as separate glyphs.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 138
9.1 Glyphs Element
Metro Specification and Reference Guide
Figure 9–6. One-to-Many Cluster Map.
9.1.2.4
Many-to-Many Mappings
In some fonts an indivisible group of UTF-16 code units for a character cluster maps to more than one glyph. For example, this is common in fonts supporting Indic scripts. When an indivisible group of UTF-16 code units maps to one or more glyphs, the value in the ClusterMap for each of the UTF-16 code units references the first glyph in the GlyphIndices array representing that codepoint. The following example shows the Unicode and glyph representations of a Tamil word having two glyph clusters. Each cluster has a base character and a combining mark. The first pair of UTF-16 code units generates three glyphs because the combining mark splits both sides of the base character. The second pair of UTF-16 code units is represented by a single glyph that incorporates the effect of the combining mark. Figure 9–7. Many-to-Many Cluster Map.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
9.1.3
9.1 Glyphs Element
139
Using the Indices Attribute to Specify Glyph Runs
Each element MAY have an Indices attribute. All of the glyph specifications within the Indices property are OPTIONAL. The GlyphIndex portion of the Indices attribute may be used to
specify a series of glyphs, complex character-to-glyph cluster mappings, or a combination of both. The Indices property may also include glyph placement information. The specification of each glyph (or glyph cluster) has the following form:
[GlyphIndex][,[Advance][,[uOffset][,[vOffset]]]] Within the Indices attribute, each glyph specification is separated by a semicolon. For example, to specify that the seventh glyph in the UnicodeString has an advance width of 40, the following syntax is used:
Indices = ";;;;;;,40" The portions of the Indices attribute are described in the following table. Table 9–1. Indices attribute
Description
portion GlyphIndex
Index of glyph (16-bit) in the physical font. The entry MAY be empty, in which case the GlyphIndex is determined by looking up the UTF-16 code unit in the font character map (cmap) table.
Advance
Advance width indicating placement for the next glyph relative to origin of this glyph. Measured in direction of advance as defined by the sideways and BidiLevel attributes. Base glyphs generally have a non-zero advance width and
In cases where character-to-glyph mappings are not one-to-one, cluster mapping specification precedes the GlyphIndex (described below).
combining glyphs have a zero advance width. Advance width is measured in 100ths of the font em size. The default value is defined in the horizontal metrics font table (HMTX) if the IsSideways flag is specified as “false” or the vertical metrics font table (VMTX) if the IsSideways flag is specified as “true”. Advance width is a real number with units specified in hundredths of an em. So that rounding errors do not accumulate, the advance MUST be calculated as the exact unrounded origin of the subsequent glyph minus the sum of the calculated (i.e., rounded) advance widths of the preceding glyphs. uOffset, vOffset
Offset relative to glyph origin to move this glyph. Used to attach marks to base characters. The value is added to the nominal glyph origin calculated using the advance width to generate the actual origin for the glyph. The setting of the
IsSideways attribute does not change the interpretation of uOffset and vOffset. Measured in 100ths of the font em size. The default offset values are 0,0. uOffset and vOffset are real numbers with a single digit of precision, allowing placement control to the 1000th of the font em size. Base glyphs generally have a glyph offset of (0,0). Combining glyphs generally have an offset that places them correctly on top of the nearest preceding base glyph.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 140
9.1 Glyphs Element
9.1.3.2
Metro Specification and Reference Guide
Specifying Character-to-Glyph Mappings
A ClusterMap specification MAY precede the glyph specification for the first glyph of the cluster. Each cluster specification has the following form:
(ClusterCodeUnitCount [:ClusterGlyphCount])
For example, to specify that the sixth and seventh UTF-16 code units in the UnicodeString should be replaced by a single glyph having index 191, the following syntax is used:
Indices = ";;;;;(2:1)191" Empty Indices values indicate that the corresponding UTF-16 code unit within the UnicodeString has a one-to-one relationship with the glyph index as specified by the character mapping table (cmap) within the font. The portions of the cluster specification are described below. Table 9–2. Cluster specification
Description
portion ClusterCodeUnitCount
Number of Unicode code units (encoding-independent) combining to form this cluster. One or more code units may be specified. Default value is 1.
ClusterGlyphCount
Number of glyph indices combining to form this cluster. One or more indices may be specified. Default value is 1.
ClusterMaps specifying 0:n or n:0 mappings are invalid.
9.1.4
Using the UnicodeString Attribute
The UnicodeString attribute holds the array of UCS-4 code points represented by this element. The UnicodeString is RECOMMENDED, as it supports searching, selection, and accessibility. If UnicodeString contains UCS-4 code points that require two UTF-16 code units, a cluster map with a many-to-one or many-to-many mapping MUST be specified for the respective UCS-4 code points. The standard XML escaping mechanisms are used to specify XML-reserved characters. Furthermore, an additional mechanism MUST be used to escape a UnicodeString value that begins with “{”. In order to use “{” at the beginning of the UnicodeString attribute, it MUST be escaped with a prefix of “{}”. If the UnicodeString attribute starts with “{}”, then a consumer MUST ignore those first two characters in processing the UnicodeString value and in calculating index positions for the characters of the UnicodeString. If the UnicodeString specifies an empty string (“” or “{}”), and the Indices attribute is missing or is also empty, no drawing occurs. Producers SHOULD avoid including Unicode control marks in the UnicodeString. Consumers MUST treat Unicode control marks that remain in the UnicodeString as spaces (i.e., no ink), and honor their advance widths, if any. Such Unicode control marks include control codes, layout controls, invisible operators, deprecated format characters, variation selectors, non-characters, and specials, according to their definition within the Unicode specification. Producers MAY choose to generate UnicodeString attribute values which are not “normalized” by any Unicode-defined algorithm. Because advance-widths, glyph indices, caret-stops, etc. are associated with the generated UnicodeString attribute value, a consumer MUST NOT normalize the UnicodeString attribute value to produce an internal representation.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
9.1.5
9.1 Glyphs Element
141
Using the StyleSimulations Attribute
Synthetic style simulations can be applied to the shape of the glyphs of a glyph run by using the StyleSimulations attribute. StyleSimulations can be applied in addition to the designed style of a
font.
The default value for the StyleSimulations attribute is “None”, in which case the shapes of glyphs are not modified from their original design in the font file. When StyleSimulation is specified as “BoldSimulation”, synthetic emboldening is applied by widening the shape of glyphs by 1% of the em size. As a result the character height and the advance width of each glyph are increased by 2% of the em size. Producers MUST layout algorithmically emboldened glyphs using advance widths 2% of the em size larger than when not algorithmically emboldened. Consumers MUST implement the effect of algorithmic emboldening such that the black box of the glyph grows by 2% of the em size. When advances widths are omitted from the markup and the glyphs are algorithmically emboldened, the advance widths obtained from the hmtx table (if IsSideways equals “false”) or the vmtx table (if IsSideways equals “true”) of the font MUST be increased by 2% of the em size. When StyleSimulation is specified as “ItalicSimulation”, synthetic italicizing is applied to glyphs of elements with IsSideways="false" by skewing the top edge of the alignment box of the character by 20 degrees to the right relative to the baseline of the character. Glyphs of elements with IsSideways="true" are italicized by skewing the right edge of the alignment box of the character by 20 degrees down relative to the baseline origin of the glyph. The character height and advance width are not modified.
Producers must layout algorithmically italicized glyphs using exactly the same advance widths as when not algorithmically italicized. When StyleSimulation is specified as “BoldItalicSimulation”, both of the above (“BoldSimulation” and “ItalicSimulation”) are applied in order.
9.1.6
Using the CaretStops Attribute to Specify Caret Placement
The CaretStops attribute contains an array of Boolean flags, represented as a string of hexadecimal characters. The flags indicate whether the corresponding UTF-16 code unit in the UnicodeString attribute is a legal position to place the caret before. The term “before” in this statement refers to a logical placement, not a physical placement. For example, if the flag is set in right-to-left text, the caret could be placed before, which is to the right of that UTF-16 code unit. The CaretStops attribute includes a final flag for placement of the caret following the final UTF-16 code unit in the UnicodeString attribute. Each hexadecimal character in the CaretStops string represents the flags for four UTF-16 code units in the UnicodeString attribute, with the highest-order bit representing the first UTF-16 code unit. Any unused bits in the last UTF-16 code unit must be 0. If the CaretStops attribute is omitted, all the UTF-16 code units in the UnicodeString are considered valid positions to place a caret before. Thus, omitting the CaretStops attribute is equivalent to specifying a string that has all the bits set to 1. If there are insufficient flags in the CaretStops string to correspond to all the UTF-16 code units in the UnicodeString, all remaining UTF-16 code units in UnicodeString MUST be considered to be valid caret stops. For example, given the following attributes, the ‘m’ in ‘example’ is not a valid caret stop position:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 142
9.1 Glyphs Element
Metro Specification and Reference Guide
UnicodeString = "This is an example string of text." CaretStops = "fffd"
9.1.7
Glyphs.Fill
element Glyphs.Fill diagram
annotation Describes the brush used to fill the shape of the rendered glyphs.
are filled with a brush (see Chapter 10, “Brushes”) in the same way a is. Any brush may be used. The brush is specified in the Fill property.
9.1.8
Sideways Text
elements for text in vertical writing systems are normally represented in Metro by rotating the coordinate system and using the IsSideways attribute on runs of glyphs. Glyphs with IsSideways set to "true" will be rotated 90 degrees counter-clockwise and placed so that the sideways baseline origin is coincident with the nominal origin of the character, as modified by the offset vector in the Indices attribute. The advance vector places the nominal origin of the next character a distance along the direction of progression of the run (a move in the positive X-direction, unless BidiLevel is odd). The direction of the advance vector is unaffected by IsSideways, however the method by which the size of the advance vector is chosen is different. For example, to represent a run of characters top to bottom of a page, a RenderTransform would be used to rotate the coordinate system 90 degrees clockwise. The OriginX and OriginY would be used to specify a position at the top of the column of text. Text from a vertical writing system can then be written using elements with the IsSideways attribute set to "true". The individual glyphs would appear in the normal orientation, because the rotation effected by the IsSideway flag undoes the effect of the RenderTransform. Text from horizontal writing systems could be included in the column by using elements without specifying IsSideways, or using a value of "false" for it. The rotated coordinate system will make them appear top to bottom on the page, but with the glyphs rotated right. If alternate vertical character representations are available in the font, the producer SHOULD use those and provide their glyph indices in the Indices attribute accordingly. 9.1.8.1
Sideways Text Origin Calculation
The origin is the top center of the unturned glyph. The vertical X-origin is calculated to be exactly one-half the advance width of the glyph, as specified in the horizontal metrics (hmtx) table for the font. In pseudocode:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
9.1 Glyphs Element
143
TopOriginX = hmtx.advanceWidth[GlyphIndex] / 2
If the font is a CFF OpenType font, the vertical Y-origin is determined from the vertical origin (vorg) table for the font, which may be specified for a particular glyph index but falls back to the default vertical origin if the glyph index is not present in the vorg table. In pseudocode:
TopOriginY = vorg.vertOriginY[glyphIndex]
Or:
TopOriginY = vorg.defaultVertOriginY If the vorg table is not present, the glyph data (glyf) and vertical metrics (vmtx) tables are consulted (only if the vmtx table exists). The glyph bounding box is retrieved from the glyph data (glyf) table and added to the top side-bearing for the glyph, specified in the vertical metrics table. In pseudocode:
TopOriginY = glyf.yMax[glyphIndex] + vmtx.topSideBearing[glyphIndex] If the vmtx table does not exist and the Windows-specifics metrics (OS/2) table exists, it is consulted and the sTypoAscender value is used. In pseudocode:
TopOriginY = os/2.sTypoAscender In any other circumstance, the Ascender value from the horizontal header (hhea) table is used. In pseudocode:
TopOriginY = hhea.Ascender
9.1.9
Device Fonts
Printer device fonts are specified in Metro Reach packages by defining the DeviceFontID attribute on the element. If a consumer of the Metro Reach package understands the specified DeviceFontID value, the consumer MAY ignore the embedded font and use the device resident version. By definition, a consumer “understands” a printer device font if it can unambiguously correlate the DeviceFontID value to a set of font metrics resident on the device. If a consumer does not understand the specified DeviceFontID value, the consumer MUST render the embedded version of the font. When rendering a printer device font, a consumer MUST use the UnicodeString property and ignore the glyph index components of the Indices property. The consumer MUST still honor the advance width and x,y offset values present in the Indices property. A element with a specified DeviceFontID MUST have exactly one Indices glyph per character in the UnicodeString attribute. Its Indices attribute MUST NOT include any cluster specificitions. Each of its Indices glyphs MUST include a specified advance width and MUST include specified x,y offset values if they are non-zero.
9.1.10 Specifying the Glyph Language Metro clients may need to override the default language for a specific run of glyphs, particularly in multilingual documents. The language value defaults to the xml:lang attribute value specified on the element, but may be overridden for a particular glyph run by specifying the xml:lang attribute on the element directly. For larger blocks of text, the writer MAY specify the xml:lang attribute on the element. The xml:lang attribute does not affect rendering of , but can be used by search or selection functionality in consumers. For more information, see Section 7.3, “Language in Reach Packages” on page 79.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 144
9.1 Glyphs Element
Metro Specification and Reference Guide
9.1.11 Glyphs Markup Examples
Fill="#00FF00" /> Fill="#00FF00" /> Fill="#00FF00" />
Fill="#00FF00" />
Fill="#00FF00" />
9.1.12 Optimizing the Size of Glyphs Markup Markup details, such as glyph indices and advance widths, can be omitted from the markup under the circumstances listed below. The following options allow optimization of commonly used simple scripts. 9.1.12.1
Optimizing Markup of Glyph Indices
Glyph indices MAY be omitted from markup where ALL of the following are true: •
There is a one-to-one mapping between the positions of UCS-4 code points in the Unicode string and the positions of glyphs in the glyph string
•
The glyph index is the value in selected cmap (character mapping) table of the font
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 146
9.1 Glyphs Element
9.1.12.2
Metro Specification and Reference Guide
Optimizing Markup of Glyph Positions
Glyph advance width MAY be omitted from the markup where: •
For glyphs that have not been algorithmically emboldened, the desired advance width is the value listed in the font’s hmtx table (if IsSideways equals “false”) or the vmtx table (if IsSideways
equals “true”).
•
For algorithmically emboldened glyphs, the desired advance width is exactly 2% larger than the values in the font’s hmtx table (if IsSideways equals “false”) or the vmtx table (if IsSideways equals “true”).
Glyph horizontal offset MAY be omitted from the markup when the offset equals zero and Glyph vertical offset MAY be omitted from the markup when the offset equals zero. This is almost always true for base characters, and commonly true for combining marks in simpler scripts. However, this is often false for combining marks in complex scripts such as Arabic and Indic.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
147
Chapter 10. Brushes
A brush is used to paint the interior of geometric shapes defined by the element, and to paint the characters rendered with a element. A brush is also used in defining the alpha-transparency mask in , , and .The FixedPage markup includes the following brushes: Table 10–1. Brush Name
Description
Fills defined geometric regions with a solid color
Fills a region with an image
Fills a region with a vector drawing
Fills a region with a linear gradient
Fills a region with a radial gradient
Attributes vary across brushes, although all brushes have an Opacity attribute. Brushes are used in some properties of the , , and elements. The use of a brush in markup is shown below:
... All brushes that are defined relative to a coordinate system (, , , ) may have a transform associated with them. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. For and , the Viewport property for the brush is transformed using that local effective render transform. For , the StartPoint and EndPoint properties are transformed. For , the Center, RadiusX, RadiusY, and GradientOrigin properties are transformed.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 148
10.2 SolidColorBrush
Metro Specification and Reference Guide
10.2 SolidColorBrush element SolidColorBrush diagram
attributes Name Opacity
Type
Use
ST_ZeroOne
Default
Fixed
1.0
Defines uniform transparency of the brush fill. The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values outside of this inclusive range are invalid.
x:Key
Color
Annotation
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified. ST_Color
required
Specifies color for filled elements. An sRGB color value specified as 6-digit hexadecimal number (‘#RRGGBB’) or an sRGB color width an alpha value specified as 8-digit hexadecimal number (‘#AARRGGBB’).
annotation Fills defined geometric regions with a uniform color.
fills define geometric regions with a solid color. If there is an alpha component of the color, it is combined in a multiplicative way with the corresponding opacity attribute in the brush. The following example illustrates the use of the in filling a .
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.3 ImageBrush
149
This markup is rendered as follows: Figure 10–2.
10.3 ImageBrush element ImageBrush diagram
attributes Name Opacity
Type ST_ZeroOne
Use
Default 1.0
x:Key
Version 0.7
Fixed
Annotation Defines uniform transparency of the brush fill. The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values outside of this inclusive range are invalid.
When the current element is defined
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 150
10.3 ImageBrush
Metro Specification and Reference Guide
in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified.
Version 0.7
Transform
ST_RscRefMatrix
Viewbox
ST_ViewBox
required
The Viewbox specifies the position and dimensions of the brush's source content. Specifies four real numbers (X, Y, width, height) separated by commas (','), where width and height MUST NOT be negative. The dimensions specified are relative to the image’s physical dimensions expressed in units of 1/96” (see ‘Image Example’ later in this chapter). The corners of the Viewbox are mapped to the corners of the Viewport, thereby providing the default clipping and transform for the brush’s source content.
Viewport
ST_ViewBox
required
The Viewport attribute specifies the region in the containing coordinate space of the prime brush tile that is possibly repeatedly applied to fill the region the brush is applied to. Specifies four real numbers (X, Y, width, height) separated by commas (','), where width and height MUST NOT be negative. The alignment of the brush pattern is controlled by adjusting the X and Y values.
Stretch
ST_Stretch
required
TileMode
ST_TileMode
Describes a MatrixTransform applied to the brush’s coordinate space. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. The Viewport for the brush is transformed using that local effective render transform.
Fill
None
Final
The Stretch attribute is used to specify how the contents of a Viewbox are mapped to a Viewport.
Specifies how contents will be tiled in the filled region. Valid values are ‘None’, ‘Tile’, ‘FlipX’, ‘FlipY’, and
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.3 ImageBrush
151
‘FlipXY’.
ViewboxUnits
ST_ViewUnits
required
Absolute
The ViewboxUnits specifies the relationship of the Viewbox coordinates to the containing coordinate space.
ViewportUnits
ST_ViewUnits
required
Absolute
The ViewportUnits specifies the relationship of the Viewport coordinates to the containing coordinate space.
ImageSource
xs:anyURI
required
Specifies URI of image resource. The URI MUST refer to a part in the package.
annotation Fills a region with an image.
can be used to fill a space with an image. The markup for allows a URI to be specified using the ImageSource attribute. The image is defined in a coordinate space specified by the resolution of the image. The image specified MUST refer to an image part within the package in one of the supported Reach image formats: JPEG, PNG, or TIFF 6.0 (for more information, see Section 6.1.6.1, “Supported Formats” on page 62). For more information, see Section 10.5, “Common Attributes for ImageBrush and VisualBrush” on page 157. The markup below demonstrates how to place an image onto a .
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 152
10.3 ImageBrush
Metro Specification and Reference Guide
This markup produces the following results: Figure 10–3.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.4 VisualBrush
153
10.4 VisualBrush element VisualBrush diagram
attributes Name Opacity
Type ST_ZeroOne
Use
Default 1.0
x:Key
Transform
Version 0.7
Fixed
Annotation Defines uniform transparency of the brush fill. The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values outside of this inclusive range are invalid.
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified. ST_RscRefMatrix
Describes a MatrixTransform applied to the brush’s coordinate space. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. The Viewport for the brush is transformed using that local effective render transform.
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 154
10.4 VisualBrush
Version 0.7
Metro Specification and Reference Guide
Viewbox
ST_ViewBox
required
The Viewbox specifies the position and dimensions of the brush's source content. Specifies four real numbers (X, Y, width, height) separated by commas (','), where width and height MUST NOT be negative. The Viewbox defines the default coordinate system for the element specified in VisualBrush.Visual. The corners of the Viewbox are mapped to the corners of the Viewport, thereby providing the default clipping and transform for the brush’s source content.
Viewport
ST_ViewBox
required
The Viewport attribute specifies the region in the containing coordinate space of the prime brush tile that is possibly repeatedly applied to fill the region the brush is applied to. Specifies four real numbers (X, Y, width, height) separated by commas (','), where width and height MUST NOT be negative. The alignment of the brush pattern is controlled by adjusting the X and Y values.
Stretch
ST_Stretch
required
TileMode
ST_TileMode
ViewboxUnits
ST_ViewUnits
required
Absolute
The ViewboxUnits specifies the relationship of the Viewbox coordinates to the containing coordinate space.
ViewportUnits
ST_ViewUnits
required
Absolute
The ViewportUnits specifies the relationship of the Viewport coordinates to the containing coordinate space.
Visual
ST_RscRef
Fill
None
The Stretch attribute is used to specify how the contents of a Viewbox are mapped to a Viewport.
Specifies how contents will be tiled in the filled region. Valid values are ‘None’, ‘Tile’, ‘FlipX’, ‘FlipY’, and ‘FlipXY’.
Specifies resource reference to a Visual defined in a ResourceDictionary. The Visual is
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.4 VisualBrush
155
used to draw the brush’s source content.
annotation VisualBrush can be used to fill a space with a vector drawing. The drawing may be specified as either a child element of VisualBrush, or as a resource reference. Drawing content is expressed using , , and elements.
For more information, see Section 10.5, “Common Attributes for ImageBrush and VisualBrush” on page 157.
can be used to fill a space with a vector drawing. The drawing may be specified as either a child element of , or as a resource reference. Drawing content may include , , and elements, and is specified inside the child element.
10.4.1 VisualBrush.Visual element VisualBrush.Visual diagram
annotation Specifies a element, element, or element used to draw the brush’s source contents.
The use of the child element in markup is shown below.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 156
10.4 VisualBrush
Metro Specification and Reference Guide
This markup produces the following result: Figure 10–4.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide10.5 Common Attributes for ImageBrush and VisualBrush157
10.5 Common Attributes for ImageBrush and VisualBrush There are a number of attributes in common between and : •
Viewbox
•
Viewport
•
ViewboxUnits
•
ViewportUnits
•
Stretch
•
TileMode
Both ImageBrush and VisualBrush assume that the background of the brush itself is initially transparent.
10.5.1 Rendering Images and Visuals The Viewbox attribute specifies the region of the source content of the brush, which is to be mapped to the Viewport. The ViewboxUnits attribute MUST have the value “Absolute”. The Viewport attribute specifies the position and dimensions of the brush tile that is repeatedly applied to fill a Path. The alignment of the brush pattern is controlled by adjusting the min-x and min-y values. The ViewportUnits attribute MUST have the value “Absolute”. Conceptually, the Viewbox specifies the portion of a source image or visual that will be rendered to the page. The Viewport specifies the target tile that will be filled with the specified image or visual fragment. That tile is then used to fill the geometry specified by the parent element.
10.5.2 Image Example For images, the dimensions specified in the Viewbox attribute are in 1/96" units. The coordinates in the image are specified in these units, as calculated by dividing the horizontal dimension of the image in pixels by the horizontal image resolution, and the vertical dimension of the image in pixels by the vertical image resolution. The image resolution must be determined by inspecting the header or tag information of the image. If no resolution information is contained in the image, a default resolution of 96dpi is assumed. The upper-left corner of the image is coordinate 0,0. Consider the following definition:
Assuming the FixedPage default coordinate system, and if tiger.jpg specifies resolution information of 50dpi and has dimensions in 100 pixels horizontally and 50 pixels vertically, the physical dimensions of the image are horizontal 96 * 100 / 50 = 192 (in units of 1/96”) and vertical 96 * 50 / 50 = 96 (in units of 1/96”). The Viewbox uses a square starting at 24,24 (a quarter-inch from left and a quarter-inch from top) in the image, and extending for 48,48 (a half-inch to the right and a half-inch down) and scales it to a square starting at one inch from the left edge of the physical page and one inch from the top of the physical page and extending two inches to the right and two inches down.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 158
10.5 Common Attributes for ImageBrush and VisualBrushMetro Specification and Reference Guide
The Viewbox can specify a region larger than the image itself, including negative values.
10.5.3 Viewbox and Viewport Examples
The following examples demonstrate how adjusting the Viewbox and Viewport attributes can affect
output.
First, here is the basic image:
This markup is rendered as follows: Figure 10–5.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide10.5 Common Attributes for ImageBrush and VisualBrush159
By adjusting the Viewport, the position of the tiles within the image can be changed:
This markup is rendered as follows: Figure 10–6.
Use a smaller window on the Viewbox to effectively “zoom in” on each tile:
This markup is rendered as follows: Figure 10–7.
10.5.4 Stretch The Stretch attribute specifies how the contents of the Viewbox are mapped to the Viewport. The value “Fill” must be specified. The portion of the content specified by the Viewbox is scaled to the bounds specified by the Viewport. The aspect ratio is not preserved.
10.5.5 TileMode The TileMode attribute specifies how the tiles are arranged in the filled geometry. This value MUST be specified. Valid values are: •
None
•
Tile
•
FlipX
•
FlipY
•
FlipXY
•
TileMode None
In this TileMode, only the single base tile is drawn. The remaining area is left as transparent.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide10.5 Common Attributes for ImageBrush and VisualBrush161
ImageBrush Example
This markup is rendered as follows: Figure 10–8.
VisualBrush Example
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 162
10.5 Common Attributes for ImageBrush and VisualBrushMetro Specification and Reference Guide
This markup is rendered as follows: Figure 10–9.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide10.5 Common Attributes for ImageBrush and VisualBrush163
10.5.5.2
TileMode Tile
In this TileMode, the base tile is drawn and the remaining area is filled by repeating the base tile such that the right edge of each tile abuts the left edge of the next, and the bottom edge of each tile abuts the top edge of the next. ImageBrush Example
This markup is rendered as follows: Figure 10–10.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 164
10.5 Common Attributes for ImageBrush and VisualBrushMetro Specification and Reference Guide
VisualBrush Example
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide10.5 Common Attributes for ImageBrush and VisualBrush165
This markup is rendered as follows: Figure 10–11.
10.5.5.3
TileMode FlipX
The tile is arranged the same as TileMode Tile, but alternate columns of tiles are flipped horizontally. The base tile is positioned as specified in the Viewport attribute. Tiles in the columns to the left and right of this tile are flipped horizontally. ImageBrush Example
This markup is rendered as follows: Figure 10–12.
VisualBrush Example
This markup is rendered as follows: Figure 10–13.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 168
10.5 Common Attributes for ImageBrush and VisualBrushMetro Specification and Reference Guide
10.5.5.4
TileMode FlipY
The tile is arranged the same as TileMode Tile, but alternate rows of tiles are flipped vertically. The base tile is positioned as specified by the Viewport attribute. Rows above and below are flipped vertically. ImageBrush Example
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide10.5 Common Attributes for ImageBrush and VisualBrush169
This markup is rendered as follows: Figure 10–14.
VisualBrush Example
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 170
10.5 Common Attributes for ImageBrush and VisualBrushMetro Specification and Reference Guide
This markup is rendered as follows: Figure 10–15.
10.5.5.5
TileMode FlipXY
The tile is arranged the same as TileMode Tile, but alternate columns of tiles are flipped horizontally and alternate rows of tiles are flipped vertically. The base tile is positioned as specified by the Viewport attribute. ImageBrush Example
This markup is rendered as follows: Figure 10–16.
VisualBrush Example
This markup is rendered as follows: Figure 10–17.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.6 GradientBrushes
173
10.6 GradientBrushes
10.6.1 LinearGradientBrush element LinearGradientBrush diagram
attributes Name Opacity
Type ST_ZeroOne
Use
Default 1.0
x:Key
Color Interpolation Mode
Version 0.7
Fixed
Annotation Defines uniform transparency of the linear gradient. The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values outside of this inclusive range are invalid.
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified. ST_Color Interpolation Mode
SRgbLinear Interpolation
Final
This attribute specifies the gamma function for color interpolation for sRGB colors. The Gamma adjustment should not be applied to the alpha component, if specified.
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 174
10.6 GradientBrushes
Metro Specification and Reference Guide
Valid values are ‘SRgbLinearInterpolation’ and ‘ScRgbLinearInterpolation’.
SpreadMethod
ST_SpreadMethod
MappingMode
ST_MappingMode
Transform
ST_RscRefMatrix
Pad
required
Describes how the brush should fill the content area outside of the primary, initial gradient area. Valid values are ‘Pad’, ‘Reflect’ and ‘Repeat’.
Absolute
Specifies that the StartPoint and EndPoint are defined in the parent’s effective coordinate space, as modified by the Transform attribute of the brush.
Describes a MatrixTransform applied to the brush’s coordinate space. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. The ‘StartPoint’ and ‘EndPoint’ are transformed using that local effective render transform.
StartPoint
ST_Point
required
Start point of the linear gradient.
EndPoint
ST_Point
required
End point of the linear gradient. The LinearGradientBrush interpolates the colors from the StartPoint to the EndPoint, where StartPoint represents offset 0, and the EndPoint represents offset 1; The Offset attribute value specified in a GradientStop relates to the offsets 0 and 1 defined by StartPoint and EndPoint.
annotation Fills a region with a linear gradient.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.6 GradientBrushes
175
The specifies a linear gradient brush along a vector.
For further details about the computation of a linear gradient, see Section 13.1.9.1, “Linear Gradients” on page 229. The following markup example shows the use of the . A page with a
rectangular path is filled with a linear gradient:
This markup is rendered as follows: Figure 10–18.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 176
10.6 GradientBrushes
10.6.1.2
Metro Specification and Reference Guide
LinearGradientBrush.GradientStops
element LinearGradientBrush.GradientStops diagram
annotation Holds a sequence of GradientStop elements.
The specifies a collection of elements that comprise the linear gradient. See Section 10.6.3, “GradientStop” on page 188 for more details. 10.6.1.3
LinearGradientBrush SpreadMethod Examples
Below are examples of the different effects produced by the SpreadMethod attribute in a
. SpreadMethod Pad In this SpreadMethod, the first color and the last color are used to fill the remaining fill area at the beginning and end, respectively.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.6 GradientBrushes
177
This markup is rendered as follows: Figure 10–19.
SpreadMethod Reflect In this SpreadMethod, the gradient stops are replayed in reverse order repeatedly to cover the fill area.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 178
10.6 GradientBrushes
Metro Specification and Reference Guide
This markup is rendered as follows: Figure 10–20.
SpreadMethod Repeat In this SpreadMethod, the gradient stops are repeated in order until the fill area is covered.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.6 GradientBrushes
179
This markup is rendered as follows: Figure 10–21.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 180
10.6 GradientBrushes
Metro Specification and Reference Guide
10.6.2 RadialGradientBrush element RadialGradientBrush diagram
attributes Name Opacity
Type ST_ZeroOne
Use
Default 1.0
x:Key
Color Interpolation Mode
Version 0.7
Fixed
Annotation Defines uniform transparency of the radial gradient. The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values outside of this inclusive range are invalid.
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified. ST_Color Interpolation Mode
SRgbLinear Interpolation
Final
This attribute specifies the gamma function for color interpolation for sRGB colors. The Gamma adjustment should not be applied to the alpha component, if specified.
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.6 GradientBrushes
181
Valid values are ‘SRgbLinearInterpolation’ and ‘ScRgbLinearInterpolation’.
Version 0.7
SpreadMethod
ST_SpreadMethod
MappingMode
ST_MappingMode
Transform
ST_RscRefMatrix
Center
ST_Point
required
Center point of the radial gradient (i.e. the center of the ellipse). The RadialGradientBrush interpolates the colors from the GradientOrigin to the circumference of the ellipse. The circumference is determined by the Center and the radii.
GradientOrigin
ST_Point
required
Origin point of the radial gradient.
RadiusX
ST_GEZero
required
Radius in the X dimension of the ellipse which defines the radial gradient.
Pad
required
Describes how the brush should fill the content area outside of the primary, initial gradient area. Valid values are ‘Pad’, ‘Reflect’ and ‘Repeat’.
Absolute
Specifies that Center, RadiusX and RadiusY are defined in the parent’s effective coordinate space, as modified by the Transform attribute of the brush.
Describes a MatrixTransform applied to the brush’s coordinate space. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. ‘Center’, ‘GradientOrigin’, ‘RadiusX’ and ‘RadiusY’ are transformed using that local effective render transform.
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 182
10.6 GradientBrushes
RadiusY
ST_GEZero
Metro Specification and Reference Guide
required
Radius in the Y dimension of the ellipse which defines the radial gradient.
annotation Fills a region with a radial gradient.
The radial gradient is similar in concept to the linear gradient. However, whereas the linear gradient has a start and end point to define the gradient vector, the radial gradient has an ellipse along with a gradient origin to define the gradient behavior. The ellipse defines the end point of the gradient. In other words, a gradient stop at 1.0 defines the color at the circumference of the ellipse. The gradient origin defines the center of the gradient. A gradient stop at 0.0 defines the color at the gradient origin. Figure 10–22 is a radial gradient that goes from white to grey. The outside ellipse represents the gradient ellipse while the dot denotes the gradient origin. This gradient has SpreadMethod attribute set to “Pad”. Figure 10–22. Radial Gradient.
For further details about the computation of a radial gradient, see Section 13.1.9.2, “Radial Gradients” on page 231. The following markup example shows the use of the . A page with a rectangular path is filled with a radial gradient:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.6 GradientBrushes
183
This markup is rendered as follows: Figure 10–23.
10.6.2.2
RadialGradientBrush.GradientStops
element RadialGradientBrush.GradientStops diagram
annotation Holds a sequence of GradientStop elements.
The specifies a collection of elements that comprise the radial gradient. See Section 10.6.3, “GradientStop” on page 188 for more details.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 184
10.6 GradientBrushes
10.6.2.3
Metro Specification and Reference Guide
RadialGradientBrush SpreadMethod Examples
Below are examples of the different effects produced by the SpreadMethod attribute in a
.
SpreadMethod Pad
In this example, the last color is used to cover the the fill area outside the ellipse.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.6 GradientBrushes
185
This markup is rendered as follows: Figure 10–24.
SpreadMethod Reflect In this example, the gradient stops are replayed in reverse order repeatedly to cover the fill area.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 186
10.6 GradientBrushes
Metro Specification and Reference Guide
This markup is rendered as follows: Figure 10–25.
SpreadMethod Repeat In this example, the gradient stops are repeated in order until the fill area is covered.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.6 GradientBrushes
187
This markup is rendered as follows: Figure 10–26.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 188
10.6 GradientBrushes
Metro Specification and Reference Guide
10.6.3 GradientStop element GradientStop diagram
attributes Name
Type
Use
Default
Fixed
Annotation
Color
ST_Color required
Specifies gradient color. An sRGB color value specified as 6-digit hexadecimal number (‘#RRGGBB’) or an sRGB color with an alpha value specified as 8-digit hexadecimal number (‘#AARRGGBB’).
Offset
xs:double required
Specifies the gradient offset. The offset indicates a point along the progression of the gradient at which a color is specified. Colors in between gradient offsets in the progression are interpolated. See the chapter on Rendering Rules for details relating to gradient computation, especially for offset values outside the range from 0.0 to 1.0.
annotation Gradient stops indicate a location and range of color progression for rendering a gradient.
The element is used by both the and to define the location and range of color progression for rendering a gradient. For , the Offset value of 0.0 is mapped the StartPoint of the gradient and the Offset 1.0 is mapped to the EndPoint. Intermediate Offset values are interpolated between these two points to determine their location. For , the offset value of 0.0 is mapped to the GradientOrigin location and the offset 1.0 is mapped to the circumference of the ellipse as determined by the Center and RadiusX or RadiusY attribute values of RadialGradientBrush. Offsets between 0.0 and 1.0 are positioned at a location interpolated between these points.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
10.7 Using a Brush as an OpacityMask
189
10.7 Using a Brush as an OpacityMask
Each pixel carries an alpha value ranging from 0.0 (completely transparent) to 1.0 (fully opaque). The alpha value is used when blending elements to achieve the visual effect of transparency. Each element can have an Opacity attribute by which the alpha value of each pixel is multiplied uniformly.
Additionally, the OpacityMask allows the specification of per-pixel opacity which controls how rendered content is blended with its destination. The opacity specified by OpacityMask is combined multiplicatively with any opacity which may already happen to be present in the alpha channel of the contents. The perpixel opacity specified by the OpacityMask is determined by looking at the alpha channel of each pixel in the mask. The color data is ignored. The alpha value of the area not marked by the brush is 0.0. The required computations for alpha blending are described in Section 13.1.10, “Opacity Computations” on page 233. An OpacityMask always has one of the brushes as a child element. The following example illustrates how an OpacityMask is used to create a fade effect on a element. The OpacityMask in the example is a linear gradient that fades from opaque black to transparent black.
In the example below, the OpacityMask is a radial gradient.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 190
10.7 Using a Brush as an OpacityMask
Metro Specification and Reference Guide
This markup is rendered as follows: Figure 10–27.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
191
Chapter 11. Shared Element Attributes
A number of elements share common property attributes or property elements. These are summarized below and detailed in the following sections. Other than the Name and FixedPage.NavigateUri attributes, these attributes and elements are also the only elements that compose their results from parent to child, as described in Section 13.1.11 ”Composition Rules” on page 235. Table 11–1. Property Attribute
Opacity
Elements
Description
Defines uniform transparency of the element. For more information, see Section 11.2, “Opacity Attribute” on page 192.
Name
Defines a hyperlink target. For more information, see Section 11.3, “Hyperlink Attributes” on page 192.
FixedPage.NavigateUri
Defines a hyperlink source. For more information, see Section 11.3, “Hyperlink Attributes” on page 192.
Table 11–2. Property Element
Description
Contains elements that may be reused by reference throughout the markup of the or children, respectively. For more information, see Section 11.4, “Resource and Resource References” on page 194.
Restricts the region to which a brush can be applied. For more information, see Section 11.5, “Clipping” on page 198.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 192
11.2 Opacity Attribute
Metro Specification and Reference Guide
Property Element
Description
Establishes a new coordinate space for the children of the parent element through the use of an affine matrix transformation. For more information, see Section 11.6, “Positioning Content” on page 203.
Specifies a new coordinate space for the children of the parent element, through the use of an affine matrix transformation. Geometry transformations (, , and ) are applied before brushes. The results are concatenated with any containing effective RenderTransform specification. For more information, see Section 11.6, “Positioning Content” on page 203. Specifies a mask of alpha values that is applied in the same fashion as the Opacity attribute, but allow different alpha values on a pixel-by-pixel basis.
11.2 Opacity Attribute The Opacity attribute is used to transparently blend the element with previously specified elements (Alpha Blending). The Opacity attribute ranges from 0 (fully transparent) to 1 (fully opaque). Values MUST fall within this range, inclusively. See Section 13.1.10, “Opacity Computations” on page 233 for more details about the Opacity attribute.
11.3 Hyperlink Attributes Hyperlink functionality in a fixed payload is provided by the Name and FixedPage.NavigateUri attributes. For a detailed overview of hyperlink functionality, see Section 6.2.2, “Hyperlinks” on page 70.
11.3.1 Name Attribute The Name attribute contains a string value that is used to identify the current element as a named, addressable point in the document for purposes of hyperlinking into the current document. Name strings SHOULD be unique within a FixedDocument, and it is RECOMMENDED that Name strings be unique within a FixedDocumentSequence. For more information, see Section 6.2.2, “Hyperlinks” on page 70. The Name value, if specified, MUST meet the following requirements. Note that these requirements match those of XML identifiers with a few additional restrictions. 1. The initial character MUST be a letter, meaning it falls within the Lu, Ll, Lo, Lt, Nl categories. 2. Trailing characters MUST be a letter or number, meaning it falls within the Lu, Ll, Lo, Lt, Nl, Mn, Mc, Nd, Lm categories.0. The category abbreviations, as defined within the Unicode Character Database specification located at http://www.unicode.org/Public/4.0-Update/UCD-4.0.0.html, are partially reproduced below.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.3 Hyperlink Attributes
193
Table 11–3.
Abbreviation
Description
Lu
Letter, Uppercase
Ll
Letter, Lowercase
Lt
Letter, Titlecase
Lm
Letter, Modifier
Lo
Letter, Other
Mn
Mark, Non-Spacing
Mc
Mark, Spacing Combining
Nd
Number, Decimal
Nl
Number, Letter
The Name attribute is optional. If it is included, the producer SHOULD also create a corresponding element in the FixedDocument part beneath the element that links to the parent . Consumers MAY ignore this attribute, but devices that support user interaction with the contents of the Reach package SHOULD support hyperlinks.
11.3.2 FixedPage.NavigateUri Attribute The FixedPage.NavigateUri attribute is used to associate a hyperlink URI with the element, making the element a valid hyperlink source. The attribute value may be a relative or absolute URI addressing, a resource external to the Reach package or internal to the Reach package. The base URI used to resolve a relative URI is that of the FixedPage part in which the element with the FixedPage.NavigateUri property appears. Thus, a hyperlink to a destination within the FixedDocument of the source MUST specify the destination in the context of the FixedDocument part, for example “FixedDoc1#MyDestination”. The FixedPage.NavigateUri attribute is optional. It SHOULD be included ONLY if the element is intended to be a hyperlink. Consumers MAY ignore this attribute, but devices that support user interaction with the contents of the Reach package SHOULD support hyperlinks.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 194
11.4 Resource and Resource References
Metro Specification and Reference Guide
11.4 Resource and Resource References
Resource dictionaries can be used to hold shareable property values, each called a resource. Any element which can be expressed as a property element value may also be held in a resource dictionary. Each resource in a resource dictionary has a key. The resource key can be used to reference the resource from an XML attribute of a property.
The and elements can carry a resource dictionary. A resource dictionary is expressed in markup as a property of the and elements. Individual resourcevalues MUST be specified within a , which in turn is embedded in the or XML element.
or MUST precede any property elements of the or . They similarly MUST precede any “contents” of the or . element FixedPage.Resources diagram
annotation Contains the resource dictionary for the FixedPage element.
An example of the use of this element follows:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.4 Resource and Resource References
195
This markup is rendered as follows: Figure 11–2.
element Canvas.Resources diagram
annotation Contains the resource dictionary for the Canvas element.
An example of the use of this element follows:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 196
11.4 Resource and Resource References
Metro Specification and Reference Guide
This is displayed as follows: Figure 11–3.
11.4.2 Defining Fixed Payload Resource Dictionaries Any MAY have one child element property. Any MAY have one child element property. The and elements MAY contain one element. Each element has a unique key within the scope of that , identified by using the Key attribute associated with the element. The Key attribute is taken from the namespace resource dictionary namespace specified in Appendix H, “Standard Namespaces and Content Types” on page 345. A resource definition MAY reference another resource definition defined earlier in the same resource dictionary or previously defined resource dictionary of an ancestor or element. Namespace prefixes in resource definitions apply in the context of the definition, rather than in the context of the resource reference. In the example below, two geometries are defined: one for a rectangle and the other for a circle.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.4 Resource and Resource References
197
11.4.3 Referencing Resources
To set a property value to a defined resource, use the form
{StaticResource key}
Where key is the same string specified with x:Key in the resource definition. {StaticResource Rectangle} references the Rectangle definition in the previous example. The context of the resource reference determines how defined resources are rendered (e.g., the transformation matrix to be applied). In the markup sample below, the rectangular region defined by the geometry objects in the dictionary will be filled by the .
11.4.4 Scoping Rules for Resolving Resource References A single Key may not be used twice in the same resource dictionary. Furthermore, the resource dictionary of an inner may re-use a Key defined in the resource dictionary of some containing or . Resource references are resolved from the innermost to the outermost resource dictionary. A resource in a resource dictionary MUST NOT contain a reference to another previouslydefined resource with the same name. A resource MUST NOT reference another resource defined after itself. When a resource reference is used to set a property of an element, various resource dictionaries are searched for a resource of the given name. If the element bearing the property is a , then the resource dictionary (if present) of that is searched for a resource of the desired name. If the element is not a then the nearest containing or is searched. If the desired name is not defined in the initially searched resource dictionary, then the next-nearest containing or is consulted. An error occurs if the search has continued to the root element and a resource of the desired name has not been found in a resource dictionary associated with that .
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 198
11.5 Clipping
Metro Specification and Reference Guide
The example below demonstrates these rules.
... ... ...
11.5 Clipping The Clip property allows the specification of a geometric area that restricts the area that will be filled with a Brush for the element. The geometry is specified via a child geometry element (, , or ), as detailed in Section 8.2, “Geometries and Figures” on page 104, or by use of the abbreviated geometry syntax, described in Section 8.2.3, “Abbreviated Geometry Syntax” on page 126. The default FillRule for geometries that do not specify a value is “EvenOdd”.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.5 Clipping
199
11.5.1 Canvas.Clip element Canvas.Clip diagram
annotation Limits the rendered region of the element.
The element applies to all child elements of the . Here is a markup example:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 200
11.5 Clipping
Metro Specification and Reference Guide
This example is rendered as follows: Figure 11–4.
11.5.2 Path.Clip element Path.Clip diagram
annotation Limits the rendered region of the element.
A clipping region may also be applied to a specific Path. This example demonstrates a more complex clipping behavior:
The markup above produces the following result: Figure 11–5.
11.5.3 Glyphs.Clip element Glyphs.Clip diagram
annotation Limits the rendered region of the element. Only portions of the element that fall within the clip region, even partially clipped characters, produce marks on the page.
In this example, abbreviated geometry syntax (see Section 8.2.3, “Abbreviated Geometry Syntax” on page 126) is used to define the clipping region:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 202
11.5 Clipping
Metro Specification and Reference Guide
This markup is rendered as follows: Figure 11–6.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.6 Positioning Content
203
11.6 Positioning Content
The and elements are the elements on which other elements are rendered. The arrangement of content is controlled by properties specified for the or , the properties specified for elements on the or , and by compositional rules defined
for the fixed payload namespace. In fixed markup, all elements are positioned relative to the current origin (0,0) of the coordinate system. The current origin can be moved by applying the RenderTransform attribute to any , , , or element. The RenderTransform property element establishes a new coordinate frame for all children of the parent element. Furthermore, geometries and brushes (see Chapter 8, “Graphics” and Chapter 10, “Brushes”) may be manipulated by setting the Transform attribute of these elements. The Transform results are concatenated with the current RenderTransform to create an effective render transformation for the local element.
11.6.1 MatrixTransform element MatrixTransform diagram
attributes Name Matrix
Type
Use
Default
Fixed
ST_MatrixBare required
Annotation Specifies the Matrix structure that defines this transformation.
x:Key
When the current element is defined in a ResourceDictionary, x:Key MUST be present and specify a name for the resource. Outside of a ResourceDictionary, x:Key MUST NOT be specified.
annotation Creates an arbitrary affine matrix transformation used to manipulate objects or coordinate systems in a twodimensional plane.
The MatrixTransform element defines an arbitrary affine matrix transformation used to manipulate the coordinate systems of elements. A 3x3 matrix is used for transformations in an x-y plane. Affine transformation matrices can be multiplied to form any number of linear transformations, such as rotation and skew (shear), followed by translation. An affine transformation matrix has its final column equal to (0, 0, 1), so only the members in the first two columns are specified. This structure appears as follows:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 204
11.6 Positioning Content
[
M11
M12
0
M21
M22
0
OffsetX
OffsetY
1
Metro Specification and Reference Guide
]
This is specified in markup by specifying only the six numbers in the first two columns, e.g., “M11,M12,M21,M22,OffsetX,OffsetY”.
The values M11, M12, M21, and M22 control linear transformations such as rotation and skew, while OffsetX and OffsetY provide positional translation. A few typical affine matrix transformation examples follow. Scaling
[
X scale-factor
0
0
0
Y scale-factor
0
0
0
1
]
Reversing the X-Axis
[
-1
0
0
0
1
0
0
0
1
]
Reversing the Y-Axis
[
1
0
0
0
-1
0
0
0
1
]
Skewing
[
1
Y skew-factor
0
X skew-factor
1
0
0
0
1
]
Rotating
[
cos Θ
sin Θ
0
-sin Θ
cos Θ
0
0
0
1
]
Positioning
[
1
0
0
0
1
0
OffsetX
OffsetY
1
Version 0.7
] Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.6 Positioning Content
205
Example
The following example rotates a box (with the top edge marked) 90° and shifts it 50 units down and to the right. Note that since the x-origin has been shifted, the overall box must be shifted the width of the box additionally to achieve the desired visual effect.
Before the render transformation, the box appeared as follows: Figure 11–7.
After the render transformation, the box appears as follows: Figure 11–8.
A MatrixTransform may also be specified as a property attribute using the following abbreviated syntax:
matrix(M11,M12,M21,M22,OffsetX,OffsetY) The following example markup results in the same image as above.
This abbreviated syntax may be used for any RenderTransform or Transform attribute.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 206
11.6 Positioning Content
Metro Specification and Reference Guide
11.6.2 FixedPage.RenderTransform element FixedPage.RenderTransform diagram
annotation RenderTransform establishes a new coordinate frame for the child elements of the FixedPage, such as a canvas. The attributes ‘BleedBox’, ‘ContentBox’, ‘W idth’ and ‘Height’ are not affected by RenderTransform.
The overall coordinate system of the may be adjusted using a . For example, the following markup causes all contents of the page to be shifted 50 units to the right:
This markup is rendered as follows: Figure 11–9.
11.6.3 Canvas.RenderTransform element Canvas.RenderTransform diagram
annotation RenderTransform establishes a new coordinate frame for the child elements of the canvas, such as another canvas. RenderTransform also affects ‘Clip’ and ‘OpacityMask’.
The following example illustrates positioning of child elements through .
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.6 Positioning Content
207
This markup is rendered as follows: Figure 11–10.
11.6.4 Path.RenderTransform element Path.RenderTransform diagram
annotation RenderTransform establishes a new coordinate frame for all attributes of the path and for all child elements of the path, such as the geometry defined by Path.Data.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 208
11.6 Positioning Content
Metro Specification and Reference Guide
The following example demonstrates a Y-skew transformation applied to a circular path. (Before the render transformation, the middle of the right edge of the circle was marked with a horizontal line.)
This markup is rendered as follows: Figure 11–11.
11.6.5 Glyphs.RenderTransform element Glyphs.RenderTransform diagram
annotation RenderTransform establishes a new coordinate frame for the glyph run specified by the element. Glyphs.RenderTransform affects Clip, OpacityMask, Fill, OriginX, OriginY, the actual shape of individual Glyphs, as well as the advance widths. Glyphs.RenderTransform also affects the font size and values specified in the Indices attribute.
In this example, the letter J is flipped vertically and repositioned:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.6 Positioning Content
209
This markup is rendered as follows: Figure 11–12.
11.6.6 GeometryGroup.Transform element GeometryGroup.Transform diagram
annotation Specifies a local transformation matrix that is applied to the all children of the GeometryGroup before it is used for filling, clipping or stroking.
This example demonstrates the cumulative effect of a render transformation on a that contains a with its own render transformations:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 210
11.6 Positioning Content
Metro Specification and Reference Guide
Prior to the transforms, this markup would have been rendered as follows: Figure 11–13.
With the transforms, it is rendered as follows: Figure 11–14.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.6 Positioning Content
211
11.6.7 CombinedGeometry.Transform element CombinedGeometry.Transform diagram
annotation Specifies a local transformation matrix that is applied to the all children of the CombinedGeometry before it is used for filling, clipping or stroking.
A transform applied to a takes place after combining the geometries but before a brush is applied, as demonstrated in this example:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 212
11.6 Positioning Content
Metro Specification and Reference Guide
This markup is rendered as follows: Figure 11–15.
11.6.8 PathGeometry.Transform element PathGeometry.Transform diagram
annotation Specifies a local transformation matrix that is applied to the all children of the PathGeometry before it is used for filling, clipping or stroking.
Here is a simple 150% zoom and positional transformation example:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.6 Positioning Content
213
This markup is rendered as follows. The pre-transform path is also shown, in light gray. Figure 11–16.
11.6.9 ImageBrush.Transform element ImageBrush.Transform diagram
annotation Describes a MatrixTransform applied to the brush’s coordinate space. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. The Viewport for the brush is transformed using that local effective render transform.
The following is an example of an image rotated 20° and repositioned within the . Notice that the itself remains untransformed; the Viewport attribute of the is transformed instead.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 214
11.6 Positioning Content
Metro Specification and Reference Guide
This markup is rendered as follows: Figure 11–17.
11.6.10
VisualBrush.Transform
element VisualBrush.Transform diagram
annotation Describes a MatrixTransform applied to the brush’s coordinate space. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. The Viewport for the brush is transformed using that local effective render transform.
In this example, a solid background and vertical pinstripe are rotated 45° to fill a frame.
This markup is rendered as follows: Figure 11–18.
11.6.11
LinearGradientBrush.Transform
element LinearGradientBrush.Transform diagram
annotation Describes a MatrixTransform applied to the brush’s coordinate space. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. The ‘StartPoint’ and ‘EndPoint’ are transformed using that local effective render transform.
This example applies a transform to the brush directly:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 216
11.6 Positioning Content
Metro Specification and Reference Guide
This markup is rendered as follows: Figure 11–19.
11.6.12
RadialGradientBrush.Transform
element RadialGradientBrush.Transform diagram
annotation Describes a MatrixTransform applied to the brush’s coordinate space. The Transform property on a brush is concatenated with the current effective RenderTransform to yield an effective render transform local to the brush. ‘Center’, ‘GradientOrigin’, ‘RadiusX’ and ‘RadiusY’ are transformed using that local effective render transform.
The following is an example of a rotation/reposition transform on a radial gradient:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.7 OpacityMask
217
This markup is rendered as follows: Figure 11–20.
11.7 OpacityMask The OpacityMask defines a variable alpha mask for the parent element. The alpha for areas not marked by the brush is 0.0.
11.7.1 Canvas.OpacityMask element Canvas.OpacityMask diagram
annotation Specifies a mask of alpha values (using only the alpha channel of a brush) that is applied to the canvas in the same fashion as the Opacity attribute, but allows different alpha value for different areas of the element.
In this example the contents of the Canvas are opaque with respect to each other, but both elements are blended with the background triangle.
This markup is rendered as follows: Figure 11–21.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.7 OpacityMask
219
11.7.2 Path.OpacityMask element Path.OpacityMask diagram
annotation Specifies a mask of alpha values (using only the alpha channel of a brush) that is applied to the path in the same fashion as the Opacity attribute, but allows different alpha value for different areas of the element.
This example shows a path that has a linear gradient both for the OpacityMask and for the Fill:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 220
11.7 OpacityMask
Metro Specification and Reference Guide
This markup is rendered as follows: Figure 11–22.
11.7.3 Glyphs.OpacityMask element Glyphs.OpacityMask diagram
annotation Specifies a mask of alpha values (using only the alpha channel of a brush) that is applied to the glyphs in the same fashion as the Opacity attribute, but allows different alpha value for different areas of the element.
This example demonstrates the use of to create text effects, in this case a tile effect:
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
11.7 OpacityMask
221
This markup is rendered as follows: Figure 11–23.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
223
Chapter 12. Color
12.1 Color Support in Reach Documents
Reach producers and consumers MUST be able to support sRGB colors (8-bit per channel). For all Metro Reach elements requiring color values, producers MUST specify sRGB color values (e.g., “#FFFFFF”), which MAY include alpha values (e.g., “#AAFFFFFF”). In addition to specifying sRGB values, producers MAY also specify extended color values using an extension namespace, including named colors, and CMYK colors. Additional color information may permit better color matching between the produers and consumers, specification of a larger range of color values, and better fidelity of color representations in end-to-end scenarios. Even if a Metro client does not support advanced color information specified in a Reach package, a client regenerating the package MUST preserve all existing color information specified using the extension namespace.
12.2 Advanced Color Extensions Design Note: Advanced color extensions are still being designed and will be added to future versions of this specification. Our goal is to support (for both vector graphics and raster images): •
sRGB color
•
scRGB color
•
CMYK color
•
N-Channel color
•
Named colors
12.3 Raster Image Color Extensions Design Note: Raster image color extensions are still being designed and will be added to future versions of this specification.
12.4 Alpha Blending and Gradient Blending Design Note: Alpha and Gradient Blending Rules are still being designed and will be added to future versions of this specification.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
225
Chapter 13. Rendering Rules
13.1 Rendering Details for Reach Markup 13.1.1 Coordinate Systems and Units
The (x,y) coordinate system is initially set up so that one unit in that coordinate system is equal to 1/96th of an inch, expressed as a real number. The origin (0,0) of the coordinate system is the left top corner of the element. The x coordinate value increases from left to right; the y value increases from top to bottom. A RenderTransform attribute can be specified on any child element to apply an affine transform to the current coordinate system. 13.1.1.1
Page Dimensions
The logical page dimensions correspond to the media size specified in the application page layout. The logical page dimensions are specified by the PageWidth and PageHeight parameters on the element. Further optional attributes on the element are used to specify detailed information about the areas of the that contain rendered content. For more information, see Section 7.5.3, “FixedPage Element” on page 85. The physical page dimensions correspond to the media size specified for printing. The physical page dimensions are specified in the PrintTicket PageMediaSize keyword. The interaction of the logical page dimensions and the physical page dimensions is a printing specific operation. See Section 6.1.9, “PrintTicket Parts” on page 68 for details about this interaction.
13.1.2 Implementation Limits The design of Reach markup does not assume fixed implementation limits. Individual Reach consumers may have specific implementation limits, due to the operating environment they are running in, but Reach markup has been designed, so that even very complex pages can be represented accurately and with high fidelity.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 226
13.1 Rendering Details for Reach Markup
Metro Specification and Reference Guide
A typical Reach consumer implementation SHOULD at least be able to process markup with the following characteristics: Table 13–1.
Characteristic
Type
Limit
Description
Comment
Coordinates/Transformation matrix elements
real number
+/- 1038
Largest and smallest coordinate values
Calculations involving numbers close to this limit within a few orders of magnitude are likely to be inaccurate
+/- 10-38
Coordinate values closest to 0 without rounding to 0.
Calculations involving numbers close to this limit within a few orders of magnitude are likely to be inaccurate
Required precision for coordinates
7 decimal digits
Nested Canvas
10
Total number of points in a PathFigure
100000
Depth of nested Canvas elements
Total number of points in a Segment
100000
Total number of points in a Geometry
100000
Total number of elements per page
1000000
Number of glyphs per
5000
element Number of elements in a single ResourceDictionary
10000
Total number of elements in all ResourceDictionaries of an individual Page
10000
Number of GradientStops in a GradientBrush
100
Number of FixedDocuments in a FixedDocumentSequence
1000
Number of s in a
1000000
Total size of canonicalized Reach markup per page
Bytes
64000000
Encountering Reach markup with characteristics outside of the Reach consumer-specific implementation limits MUST cause an error condition. The above table gives some typical minimum requirements for individual elements. In addition to that, Reach consumers will have limits on the total number of elements imposed by available memory.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
13.1 Rendering Details for Reach Markup
227
Note: In order to process large pages having a large size of markup or large number of elements Reach consumers MAY want to implement support for DiscardControl, to discard markup elements that have already been processed (streaming consumption).
13.1.3 Transforms
Reach markup supports affine transforms expressed through the RenderTransform attribute or the Transform attribute, respectively.
An affine transform is represented in Reach markup as a list ofsix real numbers: m11, m12, m21, m22, dx, dy. (For markup details see Section 11.6, “Positioning Content” on page 203.) The full matrix looks like:
m11 m21 dx
m12 m22 dy
0 0 1
A given coordinate X,Y is transformed with a RenderTransform to yield the resulting coordinate X’,Y’ by applying these computations:
X' = X * m11 + Y * m21 + dx Y' = X * m12 + Y * m22 + dy When rendering a nested element, the effective transform used for rendering is the concatenation of all the transforms specified by RenderTransform or Transform on parent elements, starting from the outermost parent element. Non-invertible transforms may be specified in Reach markup or occur as a result caused by limited numerical precision during concatenation. If a non-invertible effective transform is encountered by a Reach consumer during rendering, the Reach consumer MUST omit rendering the affected element and all of its nested child elements. If a non-invertible transform is encountered on a Brush (either directly specified on the Brush, or as a result of the Viewbox or Viewport properties, or through concatenation), the Brush MUST be treated like a fully transparent Brush. The Width and Height properties specified in the Viewbox and Viewport properties of an ImageBrush or VisualBrush MUST NOT be negative. If a non-invertible transform is encountered on a Geometry (either directly specified on the Geometry, or through concatenation), the Geometry MUST be considered as containing no area. A final, device-dependent step, using the horizontal resolution RX and vertical resolution RY of the device, converts the resulting coordinates X’,Y’ to device coordinates X”,Y”. (RX and RY are specified in device pixels per inch):
X'' = X' * RX/96 Y'' = Y' * RY/96
13.1.4 Rounding of Coordinates All computations on coordinate values SHOULD be performed with double precision. Final conversion (after all transforms have been computed) to device coordinates SHOULD retain at least as much fractional precision as a 28.4 fixed point representation before performing pixel coverage calculations. Very high resolution devices MAY use lower fractional precision to represent device coordinates.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL 228
13.1 Rendering Details for Reach Markup
Metro Specification and Reference Guide
13.1.5 Pixel Center Location/Pixel Placement/Pixel Inclusion
If a 28.4 device coordinate space is used, a pixel covers the range from x-1/32 to x+1-1/32.
1. An ideal implementation of a Reach consumer SHOULD render pixels in an 8*8 sub-pixel space and then perform an 8*8 box filter sampling and set the pixel to the resulting color value.
2. When rendering a shape, a practical implementation (e.g., a bi-tonal printing device) SHOULD turn on each pixel whose center is covered by the shape, or is touched by the shape with the shape extending beyond the pixel center in the positive X or Y direction of the device. Devices capable of sub-pixel masking MAY use sub-pixel masking instead. 0.
By definition, a shape with an area width of zero (no included area) does not touch or cover any pixel centers. A stroke with a width of zero is treated in the same manner. As a result of these rules, the behavior for very thin lines is implementation-specific: •
An implementation capable of anti-aliasing MAY draw a thin line in a way that blends with the background to varying degrees
•
A bi-tonal implementation on a printer MAY draw thin lines with or without drop-outs, or by applying half-toning, depending on the desired output quality
13.1.6 Maximum Placement Error When rendering Geometries, a Reach consumer SHOULD render curves so they appear smooth from a normal viewing distance. Reach producers MUST not assume a specific placement error for curve decomposition or rely on side-effects of a specific Reach consumer implementation.
13.1.7 Abutment of Shapes Abutting shapes sharing the same device coordinates for the end- and control-points of an edge SHOULD be rendered without overlap and without gaps. An ideal implementation would also follow this rule for shapes that are mathematically abutting without sharing device coordinates for end- and control-points of edges.
13.1.8 Clipping Behavior Clipping occurs as if a mask were created from the clip Geometry according to the pixel placement rules defined in Section 13.1.5, “Pixel Center Location/Pixel Placement/Pixel Inclusion” on page 228. An ideal Reach consumer SHOULD create such a mask in a 8*8 sub-pixel space and subsequently draw only those sub-pixels of a shape that correspond to ON sub-pixels in the mask. A practical implementation (e.g., bi-tonal printing device) SHOULD create a pixel mask according to Section 13.1.5 b) and subsequently draw only those pixels of a shape which correspond to ON pixels in the mask. In creating the mask and drawing the shape, the abutment of shapes rule (see Section 13.1.7, “Abutment of Shapes” on page 228) SHOULD be observed, so that no pixel of the shape is drawn that wouldn’t have been drawn if the clip Geometry was another abutting shape. A device capable of sub-pixel masking MAY use sub-pixel masking instead.
Version 0.7
Final
4/22/2005 10:55:00 AM
© 2005 Microsoft Corporation. All rights reserved. By using or providing feedback on these materials, you agree to the attached license agreement (also available at http://www.microsoft.com/whdc/device/print/metro.mspx).
WWW.K2PDF.COM TRIAL
WWW.K2PDF.COM TRIAL Metro Specification and Reference Guide
13.1 Rendering Details for Reach Markup
229
13.1.9 Computation of Gradients 13.1.9.1
Linear Gradients
A consumer SHOULD render an element filled with a LinearGradientBrush such that the appearance is the same as if these steps had been followed: 1. Sort all GradientStop values by their respective Offset attribute in ascending order. When 2 or more GradientStop values have the same Offset attribute, preserve their relative order while sorting. When more than 2 GradientStop values have the same Offset attribute, remove all but the first and last GradientStop values having the same Offset attribute. 2. If no GradientStop with Offset 0.0 exists, a. And no GradientStop with an Offset < 0.0 exists, create an artificial GradientStop with Offset 0.0 and the Color of the GradientStop with the smallest Offset attribute. b. And a GradientStop with an Offset < 0.0 exists, create an artificial GradientStop with Offset 0.0 and the Color linearly interpolated between the two GradientStops surrounding the Offset 0.0. Discard all GradientStops with Offset < 0.0. . 3. If no GradientStop with Offset 1.0 exists, a. And no GradientStop with an Offset > 1.0 exists, create an artificial GradientStop with Offset 1.0 and the Color of the GradientStop with the largest Offset attribute. b. And a GradientStop with an Offset > 1.0 exists, create an artificial GradientStop with Offset 1.0 and the Color linearly interpolated between the two GradientStops surrounding the Offset 1.0. Discard all GradientStops with Offset > 1.0. . 4. Transform StartPoint and EndPoint using the current effective RenderTransform (including the RenderTransform for the element being filled by the LinearGradientBrush and the brush’s Transform itself). 5. If SpreadMethod is “Pad” the colors of points on the line defined by the two points StartPoint and EndPoint are defined by interpolating the coordinates linearly, and each color component c (for R, G, B) as well as the alpha component a between the component values of the closest enclosing gradient stops:
For each offset (real number) t < 0: x(t) = (EndPointx-StartPointx)*t+StartPointx y(t) = (EndPointy-StartPointy)*t+StartPointy c(t) = cfirst a(t) = afirst Where cfirst are the color component values of the first gradient stop (after sorting) and afirst is the alpha component value at the first gradient stop (after sorting).
For each offset (real number) 0
