Pro WPF Windows Presentation Foundation in .NET 3.0
Matthew MacDonald
Pro WPF: Windows Presentation Foundation in .NET 3.0 Copyright © 2007 by Matthew MacDonald All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher. ISBN-13 (pbk): 978-1-59059-782-8 ISBN-10 (pbk): 1-59059-782-6 Printed and bound in the United States of America 9 8 7 6 5 4 3 2 1 Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. Lead Editor: Ewan Buckingham Technical Reviewer: Christophe Nasarre Editorial Board: Steve Anglin, Ewan Buckingham, Gary Cornell, Jason Gilmore, Jonathan Gennick, Jonathan Hassell, Chris Mills, Matthew Moodie, Jeff Pepper, Dominic Shakeshaft, Matt Wade Project Manager: Tracy Brown Collins Copy Edit Manager: Nicole Flores Copy Editors: Jennifer Whipple, Kim Wimpsett Assistant Production Director: Kari Brooks-Copony Production Editor: Laura Cheu Compositor and Artist: Diana Van Winkle, Van Winkle Design Proofreader: Lori Bring Indexer: Toma Mulligan Cover Designer: Kurt Krames Manufacturing Director: Tom Debolski Distributed to the book trade worldwide by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax 201-348-4505, e-mail
[email protected], or visit http://www.springeronline.com. For information on translations, please contact Apress directly at 2855 Telegraph Avenue, Suite 600, Berkeley, CA 94705. Phone 510-549-5930, fax 510-549-5939, e-mail
[email protected], or visit http://www.apress.com. The information in this book is distributed on an “as is” basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in this work. The source code for this book is available to readers at http://www.apress.com in the Source Code/ Download section and at http://www.prosetech.com.
For my wonderful family, Faria and Maya
Contents at a Glance About the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x About the Technical Reviewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
■CHAPTER 1 Introducing WPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 ■CHAPTER 2 XAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 ■CHAPTER 3 The Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 ■CHAPTER 4 Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 ■CHAPTER 5 Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ■CHAPTER 6 Dependency Properties and Routed Events . . . . . . . . . . . . . . . . . . . 143 ■CHAPTER 7 Classic Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 ■CHAPTER 8 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 ■CHAPTER 9 Pages and Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 ■CHAPTER 10 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 ■CHAPTER 11 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 ■CHAPTER 12 Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 ■CHAPTER 13 Shapes, Transforms, and Brushes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 ■CHAPTER 14 Geometries, Drawings, and Visuals . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 ■CHAPTER 15 Control Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 ■CHAPTER 16 Data Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 ■CHAPTER 17 Data Templates, Data Views, and Data Providers . . . . . . . . . . . . . . 547 ■CHAPTER 18 Lists, Trees, Toolbars, and Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 ■CHAPTER 19 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 ■CHAPTER 20 Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689 ■CHAPTER 21 Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 ■CHAPTER 22 Sound and Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775 ■CHAPTER 23 3-D Drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 ■CHAPTER 24 Custom Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843 ■CHAPTER 25 Interacting with Windows Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891 ■CHAPTER 26 ClickOnce Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 ■INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
v
Contents About the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x About the Technical Reviewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
■CHAPTER 1
Introducing WPF
.............................................1
Understanding Windows Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 WPF: A Higher-Level API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 The Architecture of WPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
■CHAPTER 2
XAML
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Understanding XAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 XAML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Properties and Events in XAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Using Types from Other Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Loading and Compiling XAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
■CHAPTER 3
The Application
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Creating an Application Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Deriving a Custom Application Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
■CHAPTER 4
Layout
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Understanding Layout in WPF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Simple Layout with the StackPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 The WrapPanel and DockPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 The Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Coordinate-Based Layout with the Canvas . . . . . . . . . . . . . . . . . . . . . . . . 111 Layout Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
vi
■CONTENTS
■CHAPTER 5
Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Understanding Content Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Specialized Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Decorators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
■CHAPTER 6
Dependency Properties and Routed Events
. . . . . . . . . . . . . 143
Understanding Dependency Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Understanding Routed Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 WPF Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
■CHAPTER 7
Classic Controls
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
The Control Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Content Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Text Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 List Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Range-Based Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
■CHAPTER 8
Windows
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
The Window Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Window Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Nonrectangular Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Vista-Style Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
■CHAPTER 9
Pages and Navigation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Understanding Page-Based Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Page-Based Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 The Page History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 The Navigation Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 XAML Browser Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
■CHAPTER 10 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Understanding Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 The WPF Command Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 Executing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 Advanced Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
vii
viii
■CONTENTS
■CHAPTER 11 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Assembly Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 Object Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
■CHAPTER 12 Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Style Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
■CHAPTER 13 Shapes, Transforms, and Brushes . . . . . . . . . . . . . . . . . . . . . . . . 371 Understanding Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 Transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 Better Brushes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 Bitmap Effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
■CHAPTER 14 Geometries, Drawings, and Visuals . . . . . . . . . . . . . . . . . . . . . . 413 Paths and Geometries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 Drawings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 Visuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
■CHAPTER 15 Control Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 Understanding Logical Trees and Visual Trees . . . . . . . . . . . . . . . . . . . . . . 449 Understanding Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 Creating Control Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 Organizing Template Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 Building More Complex Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
■CHAPTER 16 Data Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 Data Binding Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 Binding to a Database with Custom Objects . . . . . . . . . . . . . . . . . . . . . . . 509 Binding to a Collection of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 Data Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
■CONTENTS
■CHAPTER 17 Data Templates, Data Views, and Data Providers . . . . . . . 547 Data Binding Redux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 Data Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 Data Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570 Data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
■CHAPTER 18 Lists, Trees, Toolbars, and Menus . . . . . . . . . . . . . . . . . . . . . . . . 593 The ItemsControl Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 The ListView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 The TreeView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 Toolbars and Status Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
■CHAPTER 19 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 Understanding Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 Flow Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638 Read-Only Flow Document Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662 Editing a Flow Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668 Fixed Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677 Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
■CHAPTER 20 Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689 Basic Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689 Custom Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702 Print Settings and Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711 Printing Through XPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
■CHAPTER 21 Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 Understanding WPF Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 Basic Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723 Declarative Animation and Storyboards . . . . . . . . . . . . . . . . . . . . . . . . . . . 738 Animation Types Revisited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
ix
x
■CONTENTS
■CHAPTER 22 Sound and Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775 Playing WAV Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775 The MediaPlayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779 The MediaElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781 Speech . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
■CHAPTER 23 3-D Drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 3-D Drawing Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 Deeper into 3-D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815 Interactivity and Animations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
■CHAPTER 24 Custom Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843 Understanding Custom Elements in WPF . . . . . . . . . . . . . . . . . . . . . . . . . . 844 Building a Basic User Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846 Lookless Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858 Extending an Existing Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867 Custom Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875 Custom-Drawn Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
■CHAPTER 25 Interacting with Windows Forms . . . . . . . . . . . . . . . . . . . . . . . . . 891 Assessing Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891 Integrating Windows and Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894 Creating Windows with Mixed Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
■CHAPTER 26 ClickOnce Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 Application Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 A Simple ClickOnce Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919 ClickOnce Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927 The Last Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
■INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
About the Author ■MATTHEW MACDONALD is an author, educator, and Microsoft MVP. He’s a regular contributor to programming journals and the author of more than a dozen books about .NET programming, including Pro .NET 2.0 Windows Forms and Custom Controls in C# (Apress, 2005) and Pro ASP.NET 2.0 in C# 2005, Special Edition (Apress, 2006) with Mario Szpuszta. He lives in Toronto with his wife and daughter.
xi
About the Technical Reviewer ■CHRISTOPHE NASARRE is a development architect for Business Objects, a company that develops desktop and Web-based business intelligence solutions. During his spare time, Christophe writes articles for MSDN Magazine, MSDN/Vista, and ASPToday, and he has reviewed books on Win32, COM, MFC, .NET, and WPF since 1996.
xii
Acknowledgments N
o author can complete a book without a small army of helpful individuals. I’m deeply indebted to the whole Apress team, including Tracy Brown Collins, who remained unfazed as the book grew ever bigger, Laura Cheu, who troubleshot obscure figure-sizing issues, Jennifer Whipple and Kim Wimpsett, who speedily performed the copy edit, and many other individuals who worked behind the scenes indexing pages, drawing figures, and proofreading the final copy. I also owe a special thanks to Gary Cornell, who always offers invaluable advice about projects and the publishing world. Christophe Nasarre deserves my sincere thanks for his unfailingly excellent and insightful tech review comments—they’ve helped me to fill gaps and improve the overall quality of this book. I’m also thankful for the legions of die-hard bloggers on the various WPF teams, who never fail to shed light on the deepest recesses of WPF. I encourage anyone who wants to learn more about the future of WPF to track them down. Finally, I’d never write any book without the support of my wife and these special individuals: Nora, Razia, Paul, and Hamid. Thanks everyone!
xiii
Introduction W
hen .NET first appeared, it introduced a small avalanche of new technologies. There was a whole new way to write web applications (ASP.NET), a whole new way to connect to databases (ADO.NET), new typesafe languages (C# and VB .NET), and a managed runtime (the CLR). Not least among these new technologies is Windows Forms, a library of classes for building Windows applications. Although Windows Forms is a mature and full-featured toolkit, it’s hardwired to essential bits of Windows plumbing that haven’t changed much in the past ten years. Most significantly, Windows Forms relies on the Windows API to create the visual appearance of standard user interface elements such as buttons, text boxes, check boxes, and so on. As a result, these ingredients are essentially uncustomizable. For example, if you want to create a stylish glow button you need to create a custom control and paint every aspect of the button (in all its different states) using a lower-level drawing model. And don’t even think about introducing animated effects such as spinning text, shimmering buttons, shrinking windows, or live previews because you’ll have to paint every detail by hand! The Windows Presentation Foundation (WPF) changes all this by introducing a new model with entirely different plumbing. Although WPF includes the standard controls you’re familiar with, it draws every text, border, and background fill itself. As a result, WPF can provide much more powerful features that let you alter the way any piece of screen content is rendered. Using these features, you can restyle common controls such as buttons, often without writing any code. Similarly, you can use transformation objects to rotate, stretch, scale, and skew anything in your user interface, and you can even use WPF’s baked-in animation system to do it right before the user’s eyes. Underlying the new features in WPF is a powerful new infrastructure based on DirectX, the hardware-accelerated graphics API that’s commonly used in cutting-edge computer games. This means that you can use rich graphical effects without incurring the performance overhead that you’d suffer with Windows Forms. In fact, you even get advanced features such as support for video files and 3-D content. Using these features (and a good design tool), it’s possible to create eye-popping user interfaces and visual effects that would have been all but impossible with Windows Forms. Although the cutting-edge video, animation, and 3-D features often get the most attention in WPF, it’s important to note that you can use WPF to build an ordinary Windows application with standard controls and a straightforward visual appearance. In fact, it’s just as easy to use common controls in WPF as it is in Windows Forms. Even better, WPF enhances features that appeal directly to business developers, including a vastly improved data binding model, a new set of classes for printing content and managing print queues, and a document feature for displaying large amounts of formatted text. You’ll even get a new model for building page-based applications that run seamlessly in Internet Explorer and can be launched from a website, all without the usual security warnings and irritating installation prompts.
xiv
■INTRODUCTION
Overall, WPF combines the best of the old world of Windows development with new innovations for building modern, graphically rich user interfaces. Although Windows Forms applications will continue to live on for years, developers embarking on new Windows development projects should dig into WPF.
About This Book This book is an in-depth exploration of WPF for professional developers who know the .NET platform, the C# language, and the Visual Studio development environment. Previous experience with Windows Forms is useful but not required to get the most out of this book. This book provides a complete description of every major WPF feature, from XAML (the markup language used to define WPF user interfaces) to 3-D drawing and animation. Along the way, you’ll occasionally work with code that involves other features of the .NET Framework, such as the ADO.NET classes you use to query a database. These features aren’t discussed here. Instead, if you want more information about .NET features that aren’t specific to WPF, you can refer to one of the many dedicated .NET titles from Apress.
Chapter Overview This book includes 26 chapters. If you’re just starting out with WPF, you’ll find it’s easiest to read them in order, as later chapters often draw on the techniques demonstrated in earlier chapters. The following list gives you a quick preview of each chapter: Chapter 1: Introducing WPF describes the architecture of WPF, its DirectX plumbing, and the new device-independent measurement system that resizes user interfaces automatically. Chapter 2: XAML describes the XAML standard that you use to define user interfaces. You’ll learn why it was created and how it works, and you’ll create a basic WPF window using different coding approaches. Chapter 3: The Application introduces the WPF application model. You’ll see how to create single-instance and document-based WPF applications, and you’ll learn how to use the WPF threading model. Chapter 4: Layout delves into the layout panels that allow you to organize elements in a WPF window. You’ll consider different layout strategies, and you’ll build some common types of windows. Chapter 5: Content describes the WPF content control model, which allows you to place elements inside other elements to customize the look of common controls such as buttons and labels. Chapter 6: Dependency Properties and Routed Events describes how WPF extends .NET’s property and event system. You’ll see how WPF uses dependency properties to provide support for key features such as data binding and animation, and how it uses event routing to send events bubbling or tunneling through the elements in your user interface.
xv
xvi
■INTRODUCTION
Chapter 7: Classic Controls considers some of the common controls every Windows developer is familiar with, such as buttons, text boxes, and labels—and their WPF twists. Chapter 8: Windows examines how windows work in WPF. You’ll also learn how to create irregularly shaped windows and use Vista glass effects. Chapter 9: Pages and Navigation describes how you can build pages in WPF and keep track of navigation history. You’ll also see how to build a browser-hosted WPF application that can be launched from a website without a tedious installation step. Chapter 10: Commands introduces the WPF command model, which allows you to wire multiple controls to the same logical action. Chapter 11: Resources describes how resources let you embed binary files in your assembly and reuse important objects throughout your user interface. Chapter 12: Styles explains the WPF style system, which lets you apply a set of common property values to an entire group of controls. Chapter 13: Shapes, Transforms, and Brushes introduces the 2-D drawing model in WPF. You’ll learn to create shapes, alter elements with transforms, and paint exotic effects with gradients, tiles, and images. Chapter 14: Geometries, Drawings, and Visuals delves deeper into 2-D drawing. You’ll learn to create complex paths that incorporate arcs and curves, how to use complex graphics efficiently, and how to use the lower-level visual layer for optimized drawing. Chapter 15: Control Templates shows you how you can give any WPF control a dramatic new look (and new behavior) by plugging in a customized template. You’ll also see how templates allow you to build a “skinnable” application. Chapter 16: Data Binding introduces WPF data binding. You’ll see how to bind any type of object to your user interface, whether it’s an instance of a custom data class or the fullfledged ADO.NET DataSet. You’ll also learn how to convert, format, and validate data. Chapter 17: Data Templates, Data Views, and Data Providers shows some of the tricks for designing professional data-driven interfaces. Along the way, you’ll build rich data lists that incorporate pictures, controls, and selection effects. Chapter 18: Lists, Trees, Toolbars, and Menus considers WPF’s family of list controls. You’ll see data-oriented controls such as grids and trees, and command-oriented controls such as toolbars and menus. Chapter 19: Documents introduces WPF’s rich document support. You’ll learn to use flow documents to present large amounts of text in the most readable way possible, and you’ll use fixed documents to show print-ready pages. You’ll even use the RichTextBox to provide document editing. Chapter 20: Printing demonstrates WPF’s new printing model, which lets you “draw” text and shapes in a print document. You’ll also learn how to manage page settings and print queues.
■INTRODUCTION
Chapter 21: Animation explores WPF’s animation framework, which lets you integrate dynamic effects into your application using straightforward, declarative markup. Chapter 22: Sound and Video describes WPF’s media support. You’ll see how to control playback for sound and video, and how to throw in synchronized animations and live effects. Chapter 23: 3-D Drawing explores the support for drawing 3-D shapes in WPF. You’ll learn how to create, transform, and animate 3-D objects. You’ll even see how to place interactive 2-D controls on 3-D surfaces. Chapter 24: Custom Elements explores how you can extend the existing WPF controls and create your own. You’ll see several examples, including a template-based color picker, a masked text box, and a decorator that performs custom drawing. Chapter 25: Interacting with Windows Forms examines how you can combine WPF and Windows Forms content in the same application—and even in the same window. Chapter 26: ClickOnce Deployment shows how you can deploy WPF applications using the ClickOnce setup model introduced in .NET 2.0.
What You Need to Use This Book In order to run WPF applications, your computer must be running Microsoft Windows Vista or Microsoft Windows XP with Service Pack 2. In order to create WPF applications (and open the sample projects included with this book), you need to use one of the following versions of Visual Studio: • Visual Studio 2005 with .NET 3.0 and the WPF extensions • The next version of Visual Studio (code-named “Orcas”) To track down the exact links you need to install .NET 3.0 and the WPF extensions, visit the page of links for this book at http://www.prosetech.com. There’s one other option. Instead of using any version of Visual Studio, you can use Expression Blend—a graphically oriented design tool—to build and test WPF applications. Overall, Expression Blend is intended for graphic designers who spend their time creating serious eye candy, while Visual Studio is ideal for code-heavy application programmers. This book assumes you’re using Visual Studio. If you’d like to learn more about Expression Blend, you can consult one of many dedicated books on the subject, including Pro Expression Blend by Darren Lutz and Ryan Moore (Apress, 2007). Some of the examples in this book use ADO.NET data access code to query a SQL Server database. To try out these examples, you can use the script file that’s included with the sample code to install the database (on SQL Server version 2000 or later). Alternatively, you can use a file-based database component that’s also included with the sample code. This component retrieves the same data from an XML file, simulating the work of the full database component without requiring a live instance of SQL Server.
xvii
xviii
■INTRODUCTION
VISUAL STUDIO ORCAS At the time of this writing, Visual Studio Orcas was available in an early beta form. If you choose to use it, you’ll need to convert the example projects included with this book before you can open them. The first time you open one of the projects, Visual Studio will launch a conversion wizard that leads you through the process. The conversion process doesn’t change the actual code in these examples—instead, it simply updates the .csproj files to use the new format. Visual Studio Orcas offers one obvious advantage over Visual Studio 2005—it includes design-time support that allows you to build WPF user interfaces by pointing and clicking, much as you design Windows Forms applications. With Visual Studio 2005, you’re able to preview your user interfaces at design time, but you need to do much of the coding by hand. Technically, Visual Studio 2005 uses .NET 3.0, which includes WPF 1.0. Visual Studio Orcas includes .NET 3.5, with a slightly newer version of WPF. This newer, unreleased version of WPF has few significant changes. The key differences are bug fixes, performance tune-ups, and support for LINQ (a set of language extensions in .NET 3.5 that provides SQL-like querying capabilities).
Code Samples and URLs It’s a good idea to check the Apress website or http://www.prosetech.com to download the most recent up-to-date code samples. You’ll need to do this to test most of the more sophisticated code examples described in this book because the less significant details are usually left out. This book focuses on the most important sections so that you don’t need to wade through needless extra pages to understand a concept. To download the source code, surf to http://www.prosetech.com and look for the page for this book. You’ll also find a list of links that are mentioned in this book, so you can find important tools and examples without needless typing.
Feedback This book has the ambitious goal of being the best tutorial and reference for programming WPF. Toward that end, your comments and suggestions are extremely helpful. You can send complaints, adulation, and everything in between directly to
[email protected]. I can’t solve your .NET problems or critique your code, but I will benefit from information about what this book did right and wrong (or what it may have done in an utterly confusing way).
CHAPTER
1
■■■
Introducing WPF T
he Windows Presentation Foundation (WPF) is an entirely new graphical display system for Windows. WPF is designed for .NET, influenced by modern display technologies such as HTML and Flash, and is hardware-accelerated. It’s also the most radical change to hit Windows user interfaces since Windows 95. In this chapter you’ll peer into the architecture of WPF. You’ll get your first look at how it works, and you’ll see what it promises for the next generation of Windows applications.
Understanding Windows Graphics It’s hard to appreciate how dramatic WPF is without realizing that Windows developers have been using essentially the same display technology for more than ten years. A modern Windows application built with C# indirectly relies on two parts of the Windows operating system to create its user interface: • User32 provides the familiar Windows look and feel for elements such as windows, buttons, text boxes, and so on. • GDI/GDI+ provides drawing support for rendering shapes, text, and images at the cost of additional complexity (and often lackluster performance). Over the years, both technologies have been refined, and the APIs that developers use to interact with them have changed dramatically. But whether you’re crafting an application with C# and .NET 2.0, or lingering in the past with Visual Basic 6 or MFC-based C++ code, behind the scenes the same parts of the Windows operating system are at work. Newer frameworks simply deliver better wrappers for interacting with User32 and GDI/GDI+. They can provide improvements in efficiency, reduce complexity, and add prebaked features so you don’t have to code them yourself; but they can’t remove the fundamental limitations of a system component that was designed more than a decade ago.
■Note The basic division of labor between User32 and GDI/GDI+ was introduced more than 15 years ago and was well-established in Windows 3.0. Of course, User32 was simply User at that point, because software hadn’t yet entered the 32-bit world.
1
2
CHAPTER 1 ■ INTRODUCING WPF
DirectX: The New Graphics Engine Microsoft created one way around the limitations of the User32 and GDI/GDI+ libraries: DirectX. DirectX began as a cobbled-together, error-prone toolkit for creating games on the Windows platform. Its design mandate was speed, and so Microsoft worked closely with video card vendors to give DirectX the hardware acceleration needed for complex textures, special effects such as partial transparency, and three-dimensional graphics. Over the years since it was first introduced (shortly after Windows 95), DirectX has matured. It’s now an integral part of Windows, with support for all modern video cards. However, the programming API for DirectX still reflects its roots as a game developer’s toolkit. Because of its raw complexity, DirectX is almost never used in traditional types of Windows applications (such as business software). WPF changes all this. In WPF, the underlying graphics technology isn’t GDI/GDI+. Instead, it’s DirectX. Remarkably, WPF applications use DirectX no matter what type of user interface you create. That means that whether you’re designing complex three-dimensional graphics (DirectX’s forté) or just drawing buttons and plain text, all the drawing work travels through the DirectX pipeline. As a result, even the most mundane business applications can use rich effects such as transparency and antialiasing. You also benefit from hardware acceleration, which simply means DirectX hands off as much work as possible to the GPU (graphics processing unit), which is the dedicated processor on the video card.
■Note DirectX is more efficient because it understands higher-level ingredients such as textures and gradients, which can be rendered directly by the video card. GDI/GDI+ doesn’t, so it needs to convert them to pixel-by-pixel instructions, which are rendered much more slowly by modern video cards.
One component that’s still in the picture (to a limited extent) is User32. That’s because WPF still relies on User32 for certain services, such as handling and routing input and sorting out which application owns which portion of screen real estate. However, all the drawing is funneled through DirectX.
■Note This is the most significant change in WPF. WPF is not a wrapper for GDI/GDI+. Instead, it’s a replacement—a separate layer that works through DirectX.
Hardware Acceleration and WPF You’re probably aware that video cards differ in their support for specialized rendering features and optimizations. When programming with DirectX, that’s a significant headache. With WPF, it’s a much smaller concern, because WPF has the ability to perform everything it does using software calculations rather than relying on built-in support from the video card.
CHAPTER 1 ■ INTRODUCING WPF
■Note There’s one exception to WPF’s software support. Due to poor driver support, WPF only performs antialiasing for 3-D drawings if you’re running your application on Windows Vista (and you have a native Windows Vista driver for your video card). That means that if you draw three-dimensional shapes on a Windows XP computer, you’ll end up with slightly jagged edges rather than nicely smoothed lines. Antialiasing is always provided for 2-D drawings, regardless of the operating system and driver support.
Having a high-powered video card is not an absolute guarantee that you’ll get fast, hardware-accelerated performance in WPF. Software also plays a significant role. For example, WPF can’t provide hardware acceleration to video cards that are using out-of-date drivers. (If you’re using an older video card, these out-of-date drivers are quite possibly the only ones that were provided in the retail package). WPF also provides better performance under the Windows Vista operating system, where it can take advantage of the new Windows Vista Display Driver Model (WDDM). WDDM offers several important enhancements beyond the Windows XP Display Driver Model (XPDM). Most importantly, WDDM allows several GPU operations to be scheduled at once, and it allows video card memory to be paged to normal system memory if you exceed what’s available on the video card. As a general rule of thumb, WPF offers some sort of hardware acceleration to all WDDM (Windows Vista) drivers and to XPDM (Windows XP) drivers that were created after November 2004, which is when Microsoft released new driver development guidelines. Of course, the level of support differs. When the WPF infrastructure first starts up, it evaluates your video card and assigns it a rating from 0 to 2, as described in the sidebar “WPF Tiers.” Part of the promise of WPF is that you don’t need to worry about the details and idiosyncrasies of specific hardware. WPF is intelligent to use hardware optimizations where possible, but it has a software fallback for everything. So if you run a WPF application on a computer with a legacy video card, the interface will still appear the way you designed it. Of course, the software alternative may be much slower, so you’ll find that computers with older video cards won’t run rich WPF applications very well, especially ones that incorporate complex animations or other intense graphical effects. In practice, you might choose to scale down complex effects in the user interface, depending on the level of hardware acceleration that’s available in the client (as indicated by the RenderCapability.Tier property).
■Note The goal of WPF is to offload as much of the work as possible on the video card so that complex graphics routines are render-bound (limited by the GPU) rather than processor-bound (limited by your computer’s CPU). That way, you keep the CPU free for other work, you make the best use of your video card, and you are able to take advantage of performance increases in newer video cards as they become available.
3
4
CHAPTER 1 ■ INTRODUCING WPF
WPF TIERS Video cards differ significantly. When WPF assesses a video card, it considers a number of factors, including the amount of RAM on the video card, support for pixel shaders (built-in routines that calculate per-pixel effects such as transparency), and support for vertex shaders (built-in routines that calculate values at the vertexes of a triangle, such as the shading of a 3D object). Based on these details, it assigns a rendering tier value. WPF recognizes three rendering tiers. They are as follows: • Rendering Tier 0. The video card will not provide any hardware acceleration. This corresponds to a DirectX version level of less than 7.0. • Rendering Tier 1. The video card can provide partial hardware acceleration. This corresponds to a DirectX version level greater than 7.0 but less than 9.0. • Rendering Tier 2. All features that can be hardware accelerated will be. This corresponds to a DirectX version level greater than or equal to 9.0. In some situations, you might want to examine the current rendering tier programmatically, so you can selectively disable graphics-intensive features on lesser-powered cards. To do so, you need to use the static Tier property of the System.Windows.Media.RenderCapability class. But there’s one trick. To extract the tier value from the Tier property, you need to shift it 16 bits, as shown here: int renderingTier = (RenderCapability.Tier >> 16); if (renderingTier == 0) { ... } else if (renderingTier == 1) { ... } This design allows extensibility. In future versions of WPF, the other bits in the Tier property might be used to store information about support for other features, thereby creating subtiers. For more information about what WPF features are hardware-accelerated for tier 1 and tier 2, and for a list of common tier 1 and tier 2 video cards, refer to http://msdn2.microsoft.com/en-gb/library/ ms742196.aspx.
WPF: a Higher-Level API If the only thing WPF offered was hardware acceleration through DirectX, it would be a compelling improvement but not a revolutionary one. But WPF actually includes a basket of high-level services designed for application programmers. Here’s a list with some of the most dramatic changes that WPF ushers into the Windows programming world: • A weblike layout model. Rather than fix controls in place with specific coordinates, WPF emphasizes flexible flow layout that arranges controls based on their content. The result is a user interface that can adapt to show highly dynamic content or different languages.
CHAPTER 1 ■ INTRODUCING WPF
• A rich drawing model. Rather than painting pixels, in WPF you deal with primitives— basic shapes, blocks of text, and other graphical ingredients. You also have new features, such as true transparent controls, the ability to stack multiple layers with different opacities, and native 3-D support.
■Note The 3-D support in WPF is not as mature as Direct3D or OpenGL. If you are planning to design an application that makes heavy use of three-dimensional drawing (such as a real-time game), WPF 1.0 probably won’t provide the features and performance you need.
• A rich text model. After years of substandard text handling with feeble controls such as the classic Label, WPF finally gives Windows applications the ability to display rich, styled text anywhere in a user interface. You can even combine text with lists, floating figures, and other user interface elements. And if you need to display large amounts of text, you can use advanced document display features such as wrapping, columns, and justification to improve readability. • Animation as a first-class programming concept. Yes, you could use a timer to force a form to repaint itself. But in WPF, animation is an intrinsic part of the framework. You define animations with declarative tags, and WPF puts them into action automatically. • Support for audio and video media. Previous user interface toolkits, such as Windows Forms, were surprisingly limited when dealing with multimedia. But WPF includes support for playing any audio or video file supported by Windows Media Player, and it allows you to play more than one media file at once. Even more impressively, it gives you the tools to integrate video content into the rest of your user interface, allowing you to pull off exotic tricks such as placing a video window on a spinning 3-D cube. • Styles and templates. Styles allow you to standardize formatting and reuse it throughout your application. Templates allow you to change the way any element is rendered, even a core control such as the button. It’s never been easier to build modern “skinned” interfaces. • Commands. Most users realize that it doesn’t matter whether they trigger the Open command through a menu or a toolbar; the end result is the same. Now that abstraction is available to your code, you can define an application command in one place and link it to multiple controls. • Declarative user interface. Although you can construct a WPF window with code, Visual Studio takes a different approach. It serializes each window’s content to a set of XML tags in a XAML document. The advantage is that your user interface is completely separated from your code, and graphic designers can use professional tools to edit your XAML files and refine your application’s front end. (XAML is short for Extensible Application Markup Language, and it’s described in detail in Chapter 2.) • Page-based applications. Using WPF, you can build a browserlike application that lets you move through a collection of pages, complete with forward and back navigation buttons. WPF handles the messy details, such as the page history. You can even deploy your project as a browser-based application that runs right inside Internet Explorer.
5
6
CHAPTER 1 ■ INTRODUCING WPF
Resolution Independence Traditional Windows applications are bound by certain assumptions about resolution. Developers usually assume a standard monitor resolution (such as 1024 by 768 pixels), design their windows with that in mind, and try to ensure reasonable resizing behavior for smaller and larger dimensions. The problem is that the user interface in traditional Windows applications isn’t scalable. As a result, if you use a high monitor resolution that crams pixels in more densely, your application windows become smaller and more difficult to read. This is particularly a problem with newer monitors that have high pixel densities and run at correspondingly high resolutions. For example, it’s common to find consumer monitors that have pixel densities of 120 dpi or 144 dpi (dots per inch), rather than the more traditional 96 dpi. At their native resolution, these displays pack the pixels in much more tightly, creating eye-squintingly small controls and text. Ideally, applications would use higher pixel densities to show more detail. For example, a high-resolution monitor could display similarly sized toolbar icons but use the extra pixels to render sharper graphics. That way you could keep the same basic layout but offer increased clarity and detail. For a variety of reasons, this solution hasn’t been possible in the past. Although you can resize graphical content that’s drawn with GDI/GDI+, User32 (which generates the visuals for common controls) doesn’t support true scaling. WPF doesn’t suffer from this problem because it renders all user interface elements itself, from simple shapes to common controls such as buttons. As a result, if you create a button that’s 1 inch wide on your computer monitor, it can remain 1 inch wide on a high resolution monitor—WPF will simply render it in greater detail and with more pixels.
■Note Resolution independence also has advantages when printing the contents of a window, as you’ll see in Chapter 20.
This is the big picture, but it glosses over a few details. Most importantly, you need to realize that WPF bases its scaling on the system DPI setting, not the DPI of your physical display device. This makes perfect sense—after all, if you’re displaying your application on a 100-inch projector, you’re probably standing several feet back and expecting to see a jumbosize version of your windows. You don’t want WPF to suddenly scale down your application to “normal” size. Similarly, if you’re using a laptop with a high-resolution display, you probably expect to have slightly smaller windows—it’s the price you pay to fit all your information onto a smaller screen. Furthermore, different users have different preferences. Some want richer detail, while others prefer to cram in more content. So how does WPF determine how big an application window should be? The short answer is that WPF uses the system DPI setting when it calculates sizes. But to understand how this really works, it helps to take a closer look at the WPF measurement system.
CHAPTER 1 ■ INTRODUCING WPF
WPF Units A WPF window and all the elements inside it are measured using device-independent units. A single device-independent unit is defined as 1/96 of an inch. To understand what this means in practice, you’ll need to consider an example. Imagine that you create a small button in WPF that’s 96 by 96 units in size. If you’re using the standard Windows DPI setting (96 dpi), each device-independent unit corresponds to one real, physical pixel. That’s because WPF uses this calculation: [Physical Unit Size] = [Device-Independent Unit Size] ✕ [System DPI] = 1/96 inch ✕ 96 dpi = 1 pixel Essentially, WPF assumes it takes 96 pixels to make an inch because Windows tells it that through the system DPI setting. However, the reality depends on your display device. For example, consider a 20-inch LCD monitor with a maximum resolution of 1600 by 1200 pixels. Using a dash of Pythagoras, you can calculate the pixel density for this monitor, as shown here:
16002 + 12002 pixels 19 inches = 100 dpi
[Screen DPI] =
In this case, the pixel density works out to 100 dpi, which is slightly higher than what Windows assumes. As a result, on this monitor a 96-by-96-pixel button will be slightly smaller than 1 inch. On the other hand, consider a 15-inch LCD monitor with a resolution of 1024 by 768. Here, the pixel density drops to about 85 dpi, so the 96-by-96 pixel button appears slightly larger than 1 inch. In both these cases, if you reduce the screen size (say, by switching to 800 by 600 resolution), the button (and every other screen element) will appear proportionately larger. That’s because the system DPI setting remains at 96 dpi. In other words, Windows continues to assume it takes 96 pixels to make an inch, even though at a lower resolution it takes far fewer pixels.
■Tip As you no doubt know, LCD monitors are designed with a single resolution, which is called the native resolution. If you lower the resolution, the monitor must use interpolation to fill in the extra pixels, which can cause blurriness. To get the best display, it’s always best to use the native resolution. If you want larger windows, buttons, and text, consider modifying the system DPI setting instead (as described next).
7
8
CHAPTER 1 ■ INTRODUCING WPF
System DPI So far, the WPF button example works exactly the same as any other user interface element in any other type of Windows application. The difference is the result if you change the system DPI setting. In the previous generation of Windows, this feature was sometimes called large fonts. That’s because the system DPI affects the system font size but often leaves other details unchanged.
■Note Many Windows applications don’t fully support higher DPI settings. At worst, increasing the system DPI can result in windows that have some content that’s scaled up, and other content that isn’t, which can lead to obscured content and even unusable windows.
This is where WPF is different. WPF respects the system DPI setting natively and effortlessly. For example, if you change the system DPI setting to 120 dpi (a common choice for users of large high-resolution screens), WPF assumes that it needs 120 pixels to fill an inch of space. WPF uses the following calculation to figure out how it should translate its logical units to physical device pixels: [Physical Unit Size] = [Device-Independent Unit Size] ✕ [System DPI] = 1/96 inch ✕ 120 dpi = 1.25 pixels In other words, when you set the system DPI to 120 dpi, the WPF rendering engine assumes one device-independent unit equals 1.25 pixels. If you show a 96-by-96 button, the physical size will actually be 120 by 120 pixels (because 96 ✕ 1.25 = 120). This is the result you expect—a button that’s 1 inch on a standard monitor remains 1 inch in size on a monitor with a higher pixel density. This automatic scaling wouldn’t help much if it only applied to buttons. But WPF uses device-independent units for everything it displays, including shapes, controls, text, and any other ingredient you put in a window. As a result, you can change the system DPI to whatever you want, and WPF will adjust the size of your application seamlessly.
■Note Depending on the system DPI, the calculated pixel size may be a fractional value. You might assume that WPF simply rounds off your measurements to the nearest pixel. (In fact, WPF supports a pixel-snapping feature that does exactly this, and you’ll learn how to enable it for specific bits of content in Chapter 13.) However, by default, WPF does something different. If an edge of an element falls between pixels, it uses antialiasing to blend that edge into the adjacent pixels. This might seem like an odd choice, but it actually makes a fair bit of sense. Your controls won’t necessarily have straight, clearly defined edges if you use custom-drawn graphics to skin them; so some level of antialiasing is already necessary.
CHAPTER 1 ■ INTRODUCING WPF
The steps for adjusting the system DPI depend on the operating system. In Windows XP, you follow these steps: 1. Right-click your desktop and choose Display. 2. Choose the Settings tab and click Advanced. 3. On the General tab, choose Normal Size (96 dpi), or Large Size (120 dpi). These are the two recommended options for Windows XP, because custom DPI settings are less likely to be supported by older programs. To try out a custom DPI setting, choose Custom Setting. You can then specify a specific percentage value. (For example, 175% scales the standard 96 dpi to 168 dpi.) Here’s what to do to change system DPI in Windows Vista: 1. Right-click your desktop and choose Personalize. 2. In the list of links on the left, choose Adjust Font Size (DPI). 3. Choose between 96 or 120 dpi. Or click Custom DPI to use a custom DPI setting. You can then specify a percentage value, as shown in Figure 1-1. (For example, 175% scales the standard 96 dpi to 168 dpi.) In addition, when using a custom DPI setting, you have an option named Use Windows XP Style DPI Scaling, which is described in the sidebar “DPI Scaling with Windows Vista.”
Figure 1-1. Changing the system DPI
9
10
CHAPTER 1 ■ INTRODUCING WPF
DPI SCALING WITH WINDOWS VISTA Because older applications are notoriously lacking in their support for high DPI settings, Windows Vista uses a new technique: bitmap scaling. If you run an application that doesn’t appear to support high DPI settings, Windows Vista resizes the contents of the Window to the desired DPI, just as if it were an image. The advantage is that the application still believes it’s running at the standard 96 dpi. Windows seamlessly translates input (such as mouse clicks) and routes them to the right place in the application’s “real” coordinate system. The scaling algorithm that Windows Vista uses is a fairly good one—it respects pixel boundaries to avoid blurry edges and uses the video card hardware where possible to increase speed—but it inevitably leads to a fuzzier display. It also has a serious limitation in that Windows can’t recognize older applications that do support high DPI settings. That’s because applications need to include a manifest or call SetProcessDPIAware (in User32) to advertise their high DPI support. Although WPF applications handle this step correctly, applications prior to Windows Vista won’t use either approach and will be stuck with the less than ideal bitmap scaling. There are two possible solutions. If you have a few specific applications that support high DPI settings but don’t indicate it, you can configure that detail manually. To do so, right-click the shortcut that starts the application (in the Start menu) and choose Properties. In the Compatibility tab, switch on the option named Disable Display Scaling on High DPI Settings. If you have a lot of applications to configure, this gets tiring fast. The other possible solution is to disable bitmap scaling altogether. To do so, choose the Use Windows XP Style DPI Scaling option in the Custom DPI Setting dialog box shown in Figure 1-1. The only limitation of this approach is that there may be some applications that won’t display properly (and possibly won’t be usable) at high DPI settings. By default, Use Windows XP Style DPI Scaling is checked for DPI sizes of 120 or less but unchecked for DPI sizes that are greater.
Bitmap and Vector Graphics When you work with ordinary controls, you can take WPF’s resolution independence for granted. WPF takes care of making sure that everything has the right size automatically. However, if you plan to incorporate images into your application you can’t be quite as casual. For example, in traditional Windows applications, developers use tiny bitmaps for toolbar commands. In a WPF application, this approach is not ideal because the bitmap may display artifacts (becoming blurry) as it’s scaled up or down according to the system DPI. Instead, when designing a WPF user interface even the smallest icon is generally implemented as a vector graphic. Vector graphics are defined as a set of shapes, and as such they can be easily scaled to any size.
■Note Of course, drawing a vector graphic takes more time than painting a basic bitmap, but WPF includes optimizations that are designed to lessen the overhead to ensure that drawing performance is reasonable for any business application and most consumer-oriented ones as well.
It’s difficult to overestimate the importance of resolution independence. At first glance, it seems like a straightforward, elegant solution to a time-honored problem (which it is). However, in order to design interfaces that are fully scalable, developers need to embrace a new way of thinking.
CHAPTER 1 ■ INTRODUCING WPF
Windows Forms Lives On WPF is the platform for the future of Windows development. However, it won’t display Windows Forms overnight. Windows Forms is in many ways the culmination of the display technology built on GDI/GDI+ and User32. It’s more mature than WPF and still includes features that haven’t made their way into the WPF toolkit (such as the WebBrowser control, the DataGridView control, and the HelpProvider component). So which platform should you choose when you begin designing a new Windows application? If you’re starting from the ground up, WPF is an ideal choice and it offers the best prospects for future enhancements and longevity. Similarly, if you need one of the features that WPF provides and Windows Forms does not—such as 3-D drawing or page-based applications—it makes sense to make the shift. On the other hand, if you have a considerable investment in a Windows Forms–based business application, there’s no need to recode your application for WPF. The Windows Forms platform will continue to be supported for years to come. Perhaps the best part of the story is the fact that Microsoft has invested considerable effort in building an interoperability layer between WPF and Windows Forms (which plays a similar role to the interoperability layer that allows .NET applications to continue to use legacy COM components). In Chapter 25, you’ll learn how to use this support to host Windows Forms controls inside a WPF application, and vice versa. WPF offers similarly robust support for integrating with older Win32-style applications.
DirectX Also Lives On There’s one area where WPF isn’t a good fit: when creating applications with demanding real-time graphics, such as complex physics-based simulators or cutting-edge action games. If you want the best possible video performance for these types of applications, you’ll need to program at a much lower level and use raw DirectX. You can download the managed .NET libraries for DirectX programming at http://msdn.microsoft.com/directx and learn a bit more about DirectX at http://www.gotdotnet.com/team/directx/learn.
Silverlight Like the .NET Framework itself, WPF is a Windows-centric technology. That means that WPF applications can only be used on computers running the Windows operating system (specifically, Windows XP or Windows Vista). Browser-based WPF applications are similarly limited—they can only run on Windows computers, and they can only be hosted inside Internet Explorer. There are some workarounds to support other browsers, but they’re limited. These restrictions won’t change—after all, part of Microsoft’s goal with WPF is to take advantage of the rich capabilities of Windows computers and its investment in technologies such as DirectX. However, there is a new emerging project named Silverlight that’s designed to take a subset of the WPF platform, host it in any modern browser using a plug-in (including Firefox and Safari), and open it up to other operating systems (such as Linux and Mac OS). This is an ambitious project, and it’s still not clear how much developer interest it will attract and how good its cross-platform support will be. Microsoft has already released early previews of the Silverlight technology, which was originally named WPF/E (WPF Everywhere) because it provides a subset of the features in WPF.
11
12
CHAPTER 1 ■ INTRODUCING WPF
Although the programming libraries in Silverlight are based on WPF, the underlying plumbing is obviously quite a bit different. Here are some of the key details: • Silverlight uses XAML (the WPF markup standard for defining user interfaces), but not C#. Instead, your event handling code is written in JavaScript. • Silverlight does not require the .NET runtime, nor does it support it. (In other words, code that targets Silverlight can’t use the .NET libraries or other .NET components.) • Silverlight supports some impressive parts of the WPF platform, including video, animation, and two-dimensional drawing. The areas it doesn’t support are currently even larger, including data binding, documents, and three-dimensional drawing. The ultimate goal of Silverlight is to provide a powerful developer-oriented competitor for Adobe Flash. However, Flash has a key advantage—it’s used throughout the Web, and the Flash plug-in is installed just about everywhere. In order to entice developers to switch to a new, less-established technology, Microsoft will need to make sure Silverlight has next-generation features, rock-solid compatibility, and unrivalled design support. Depending on your perspective, Silverlight may appear to be a high-powered Flash killer, or a crippled version of WPF for Windows. But until it evolves, most developers are reserving judgment. You can learn more about Silverlight at http://msdn2.microsoft.com/en-us/asp.net/ bb187358.aspx.
■Note Silverlight also exposes some interesting options for integration with ASP.NET. Web developers could use a mix of technologies to create server-side web applications (with ASP.NET) that include rich client-side components (built in Silverlight) and even allow the pieces to communicate (using ASP.NET AJAX). In other words, Silverlight has two potential audiences: web developers who are seeking to create more interactive applications, and Windows developers who are seeking to get a broader reach for their applications. It’s too soon to tell where Silverlight will have more success.
The Architecture of WPF WPF uses a multilayered architecture. At the top, your application interacts with a high-level set of services that are completely written in managed C# code. The actual work of translating .NET objects into Direct3D textures and triangles happens behind the scenes, using a lowerlevel unmanaged component called milcore.dll.
■Note Milcore.dll is implemented in unmanaged code because it needs tight integration with Direct3D and because it’s extremely performance-sensitive.
Figure 1-2 shows the layers at work in a WPF application.
CHAPTER 1 ■ INTRODUCING WPF
The Managed WPF API
PresentationFramework.dll PresentationCore.dll
WindowsBase.dll
milcore.dll
WindowsCodecs.dll
Direct3D
User32
The Media Integration Layer
Figure 1-2. The architecture of WPF Figure 1-2 includes these key components: • PresentationFramework.dll holds the top-level WPF types, including those that represent windows, panels, and other types of controls. It also implements higher-level programming abstractions such as styles. Most of the classes you’ll use directly come from this assembly. • PresentationCore.dll holds base types, such as UIElement and Visual, from which all shapes and controls derive. If you don’t need the full window and control abstraction layer, you can drop down to this level and still take advantage of WPF’s rendering engine. • WindowsBase.dll holds even more basic ingredients that have the potential to be reused outside of WPF, such as DispatcherObject and DependencyObject, which introduces the plumbing for dependency properties (a topic you’ll explore in detail in Chapter 6). • milcore.dll is the core of the WPF rendering system and the foundation of the Media Integration Layer (MIL). Its composition engine translates visual elements into the triangle and textures that Direct3D expects. Although milcore.dll is considered a part of WPF, it’s also an essential system component for Windows Vista. In fact, the Desktop Window Manager (DWM) in Windows Vista uses milcore.dll to render the desktop.
■Note Milcore.dll is sometimes referred to as the engine for “managed graphics.” Much as the common language runtime (CLR) manages the lifetime of a .NET application, milcore.dll manages the display state. And just as the CLR saves you from worrying about releasing objects and reclaiming memory, milcore.dll saves you from thinking about invalidating and repainting a window. You simply create the objects with the content you want to show, and milcore.dll paints the appropriate portions of the window as it is dragged around, covered and uncovered, minimized and restored, and so on.
13
14
CHAPTER 1 ■ INTRODUCING WPF
• WindowsCodecs.dll is a low-level API that provides imaging support (for example, processing, displaying, and scaling bitmaps and JPEGs). • Direct3D is the low-level API through which all the graphics in a WPF are rendered. • User32 is used to determine what program gets what real estate. As a result, it’s still involved in WPF, but it plays no part in rendering common controls. The most important fact that you should realize is the Direct3D renders all the drawing in WPF. It doesn’t matter whether you have a modest video card or a much more powerful one, whether you’re using basic controls or drawing more complex content, or whether you’re running your application on Windows XP or Windows Vista. Even two-dimensional shapes and ordinary text are transformed into triangles and passed through the 3-D pipeline. There is no fallback to GDI+ or User32.
The Class Hierarchy Throughout this book, you’ll spend most of your time exploring the WPF namespaces and classes. But before you begin, it’s helpful to take a first look at the hierarchy of classes that leads to the basic set of WPF controls. Figure 1-3 shows a basic overview with some of the key branches of the class hierarchy. As you continue through this book, you’ll dig into these classes (and their relatives) in more detail.
DispatcherObject
Legend Abstract Class
DependencyObject Concrete Class Visual
UIElement
FrameworkElement
Shape
Control
ContentControl
ItemsControl
Figure 1-3. The fundamental classes of WPF
Panel
CHAPTER 1 ■ INTRODUCING WPF
The following sections describe the core classes in this diagram. Many of these classes lead to whole branches of elements (such as shapes, panels, and controls).
■Note The core WPF namespaces begin with System.Windows (for example, System.Windows, System.Windows.Controls, and System.Windows.Media). The sole exception is namespaces that begin with System.Windows.Forms, which are part of the Windows Forms toolkit.
System.Threading.DispatcherObject WPF applications use the familiar single-thread affinity (STA) model, which means the entire user interface is owned by a single thread. It’s not safe to interact with user interface elements from another thread. To facilitate this model, each WPF application is governed by a dispatcher that coordinates messages (which result from keyboard input, mouse movements, and framework processes such as layout). By deriving from DispatcherObject, every element in your user interface can verify whether code is running on the correct thread and access the dispatcher to marshal code to the user interface thread. You’ll learn more about the WPF threading model in Chapter 3.
System.Windows.DependencyObject In WPF, the central way of interacting with onscreen elements is through properties. Early on in the design cycle, the WPF architects decided to create a more powerful property model that baked in features such as change notification, inherited default values, and more economical property storage. The ultimate result is the dependency property feature, which you’ll explore in Chapter 6. By deriving from DependencyObject, WPF classes get support for dependency properties.
System.Windows.Media.Visual Every element that appears in a WPF is, at heart, a Visual. You can think of the Visual class as a single drawing object, which encapsulates drawing instructions, additional details about how the drawing should be performed (such as clipping, opacity, and transformation settings), and basic functionality (such as hit testing). The Visual class also provides the link between the managed WPF libraries and the milcore.dll that renders your display. Any class that derives from Visual has the ability to be displayed on a window. If you prefer to create your user interface using a lightweight API that doesn’t have the higher-level framework features of WPF, you can program directly with Visual objects, as described in Chapter 14.
System.Windows.UIElement UIElement adds support for WPF essentials such as layout, input, focus, and events (which the WPF team refers to by the acronym LIFE). For example, it’s here that the two-step measure and arrange layout process is defined, which you’ll learn about in Chapter 4. It’s also here that raw mouse clicks and key presses are transformed to more useful events such as MouseEnter. As with properties, WPF implements an enhanced event-passing system called routed events.
15
16
CHAPTER 1 ■ INTRODUCING WPF
You’ll learn how it works in Chapter 6. Finally, UIElement adds supports for commands (Chapter 10).
System.Windows.FrameworkElement FrameworkElement is the final stop in the core WPF inheritance tree. It implements some of the members that are merely defined by UIElement. For example, UIElement sets the foundation for the WPF layout system, but FrameworkElement includes the key properties (such as HorizontalAlignment and Margin) that support it. UIElement also adds support for data binding, animation, and styles, all of which are core features.
System.Windows.Shapes.Shape Basic shapes classes, such as Rectangle, Polygon, Ellipse, Line, and Path, derive from this class. These shapes can be used alongside more traditional Windows widgets, such as buttons and text boxes. You’ll start building shapes in Chapter 13.
System.Windows.Controls.Control A control is an element that can interact with the user. It obviously includes classes such as TextBox, Button, and ListBox. The Control class adds additional properties for setting the font and the foreground and background colors. But the most interesting detail it provides is template support, which allows you to replace the standard appearance of a control with your own stylish drawing. You’ll learn about control templates in Chapter 15.
■Note In Windows Forms programming, every visual item in a form is referred to as a control. In WPF, this isn’t the case. Visual items are called elements, and only some elements are actually controls (those that can receive focus and interact with the user). To make this system even more confusing, many elements are defined in the System.Windows.Controls namespace, even though they don’t derive from System.Windows. Controls.Control and aren’t considered controls. One example is the Panel class.
System.Windows.Controls.ContentControl This is the base class for all controls that have a single piece of content. This includes everything from the humble Label to the Window. The most impressive part of this model (which is described in more detail in Chapter 5) is the fact that this single piece of content can be anything from an ordinary string to a layout panel with a combination of other shapes and controls.
System.Windows.Controls.ItemsControl This is the base class for all controls that show a collection of items, such as the ListBox and TreeView. List controls are remarkably flexible—for example, using the features that are built into the ItemsControl class you can transform the lowly ListBox into a list of radio buttons, a list of check boxes, a tiled display of images, or a combination of completely different elements that you’ve chosen. In fact, in WPF menus, toolbars, and status bars are actually
CHAPTER 1 ■ INTRODUCING WPF
specialized lists, and the classes that implement them all derive from ItemsControl. You’ll start using lists in Chapter 16 when you consider data binding. You’ll learn to enhance them in Chapter 17, and you’ll consider the most specialized list controls in Chapter 18.
System.Windows.Controls.Panel This is the base class for all layout containers—elements that can contain one or more children and arrange them according to specific layout rules. These containers are the foundation of the WPF layout system, and using them is the key to arranging your content in the most attractive, flexible way possible. Chapter 4 explores the WPF layout system in more detail.
The Last Word In this chapter, you took your first look at WPF and the promise it holds. You considered the underlying architecture and briefly considered the core classes. WPF is the beginning of the future of Windows development. In time, it will become a system like User32 and GDI/GDI+, on top of which more enhancements and higher-level features are added. Eventually, WPF will allow you to design applications that would be impossible (or at least thoroughly impractical) using Windows Forms. Clearly, WPF introduces many dramatic changes. However, there are five key principles that immediately stand out because they are so different from previous Windows user interface toolkits such as Windows Forms. These principles are the following: • Hardware acceleration. All WPF drawing is performed through DirectX, which allows it to take advantage of the latest in modern video cards. • Resolution independence. WPF is flexible enough to scale up or down to suit your monitor and display preferences, depending on the system DPI setting. • No fixed control appearance. In traditional Windows development, there’s a wide chasm between controls that can be tailored to suit your needs (which are known as owner-drawn controls) and those that are rendered by the operating system and essentially fixed in appearance. In WPF, everything from a basic Rectangle to a standard Button or more complex Toolbar is drawn using the same rendering engine and completely customizable. For this reason, WPF controls are often called lookless controls— they define the functionality of a control, but they don’t have a hard-wired “look.” • Declarative user interfaces. In the next chapter, you’ll consider XAML, the markup standard you use to define WPF user interfaces. XAML allows you to build a window without using code. Impressively, XAML doesn’t limit you to fixed, unchanging user interfaces. You can use tools such as data binding and triggers to automate basic user interface behavior (such as text boxes that update themselves when you page through a record source, or labels that glow when you hover overtop with the mouse), all without writing a single line of C#. • Object-based drawing. Even if you plan to work at the lower-level visual layer (rather than the higher-level element layer), you won’t work in terms of painting and pixels. Instead, you’ll create shape objects and let WPF maintain the display in the most optimized manner possible.
17
18
CHAPTER 1 ■ INTRODUCING WPF
You’ll see these principles at work throughout this book. But before you go any further, it’s time to learn about a complementary standard. The next chapter introduces XAML, the markup language used to define WPF user interfaces.
CHAPTER
2
■■■
XAML X
AML (short for Extensible Application Markup Language, and pronounced “zammel”) is a markup language used to instantiate .NET objects. Although XAML is a technology that can be applied to many different problem domains, its primary role in life is to construct WPF user interfaces. In other words, XAML documents define the arrangement of panels, buttons, and controls that make up the windows in a WPF application. It’s unlikely that you’ll write XAML by hand. Instead, you’ll use a tool that generates the XAML you need. If you’re a graphic designer, that tool is likely to be a graphical design and drawing program such as Microsoft Expression Blend. If you’re a developer, you’ll probably start with Visual Studio. Because both tools are equally at home with XAML, you can create a basic user interface with Visual Studio and then hand it off to a crack design team that can polish it up with custom graphics in Expression Blend. In fact, this ability to integrate the workflow between developers and designers is one of the key reasons that Microsoft created XAML. In this chapter, you’ll get a detailed introduction to XAML. You’ll consider its purpose, its overall architecture, and its syntax. Once you understand the broad rules of XAML, you’ll know what is and isn’t possible in a WPF user interface—and how to make changes by hand when it’s necessary. More importantly, by exploring the tags in a WPF XAML document you can learn a bit about the object model that underpins WPF user interfaces and get ready for the deeper exploration to come.
■Note Currently, WPF developers need to write more than a little XAML by hand because the WPF extensions for Visual Studio 2005 aren’t terribly sophisticated. They’re able to show a graphical representation of the WPF windows you create, but they don’t offer a true drag-drop-and-configure design experience. Future versions of Visual Studio (which were in early beta at the time of this writing) will offer far superior design support.
Understanding XAML Developers realized long ago that the most efficient way to tackle complex, graphically rich applications is to separate the graphical portion from the underlying code. That way, artists can own the graphics, and developers can own the code. Both pieces can be designed and refined separately, without any versioning headaches. 19
20
CHAPTER 2 ■ XAML
Graphical User Interfaces Before WPF With traditional display technologies, there’s no easy way to separate the graphical content from the code. The key problem with Windows Forms application is that every form you create is defined entirely in C# code. As you drop controls onto the design surface and configure them, Visual Studio quietly adjusts the code in the corresponding form class. Sadly, graphic designers don’t have any tools that can work with C# code. Instead, artists are forced to take their content and export it to a bitmap format. These bitmaps can then be used to skin windows, buttons, and other controls. This approach works well for straightforward interfaces that don’t change much over time, but it’s extremely limiting in other scenarios. Some of its problems include the following: • Each graphical element (background, button, and so on) needs to be exported as a separate bitmap. That limits the ability to combine bitmaps and use dynamic effects such as antialiasing, transparency, and shadows. • A fair bit of user interface logic needs to be embedded in the code by the developer. This includes button sizes, positioning, mouse-over effects, and animations. The graphic designer can’t control any of these details. • There’s no intrinsic connection between the different graphical elements, so it’s easy to end up with an unmatched set of images. Tracking all these items adds complexity. • Bitmaps can’t be resized without compromising their quality. For that reason, a bitmapbased user interface is resolution-dependent. That means it can’t accommodate large monitors and high-resolution displays, which is a major violation of the WPF design philosophy. If you’ve ever been through the process of designing a Windows Forms application with custom graphics in a team setting, you’ve put up with a lot of frustration. Even if the interface is designed from scratch by a graphic designer, you’ll need to recreate it with C# code. Usually, the graphic designer will simply prepare a mock-up that you need to translate painstakingly into your application. WPF solves this problem with XAML. When designing a WPF application in Visual Studio, the window you’re designing isn’t translated into code. Instead, it’s serialized into a set of XAML tags. When you run the application, these tags are used to generate the objects that compose the user interface.
■Note It’s important to understand that WPF doesn’t require XAML. There’s no reason Visual Studio couldn’t use the Windows Forms approach and create code statements that construct your WPF windows. But if it did, your window would be locked into the Visual Studio environment and available to programmers only.
In other words, WPF doesn’t require XAML. However, XAML opens up worlds of possibilities for collaboration, because other design tools understand the XAML format.
CHAPTER 2 ■ XAML
■Tip XAML plays the same role for Windows applications as control tags do for ASP.NET web applications. The difference is that the ASP.NET tagging syntax is designed to look like HTML, so designers can craft web pages using ordinary web design applications such as FrontPage and Dreamweaver. As with WPF, the actual code for an ASP.NET web page is usually placed in a separate file to facilitate this design.
The Variants of XAML There are actually several different ways people use the term XAML. So far, we’ve used it to refer to the entire language of XAML, which is an all-purpose XML-based syntax for representing a tree of .NET objects. (These objects could be buttons and text boxes in a window, or custom classes you’ve defined. In fact, XAML could even be used on other platforms to represent non-.NET objects.) The official specification for XAML isn’t yet released. There are also several subsets of XAML: • WPF XAML encompasses the elements that describe WPF content, such as vector graphics, controls, and documents. Currently, it’s the most significant application of XAML, and it’s the subset we’ll explore in this book. • XPS XAML is the part of WPF XAML that defines an XML representation for formatted electronic documents. It’s been published as the separate XML Paper Specification (XPS) standard. You’ll explore XPS in Chapter 19. • WPF/E XAML (also known as WPF/Everywhere) is a subset of WPF XAML that’s intended for cross-platform use. It will be supported by plug-ins for various browsers including Internet Explorer, Firefox, and Safari. At the time of this writing, WPF/E wasn’t yet released. It’s expected to omit many of the controls that are available in the full WPF platform and all the three-dimensional rendering features. • WF XAML encompasses the elements that describe Windows Workflow Foundation (WF) content. You can learn more about WF at http://wf.netfx3.com.
XAML Compilation The creators of WPF knew that XAML needed to not just solve the problem of design collaboration—it also needed to be fast. And though XML-based formats such as XAML are flexible and easily portable to other tools and platforms, they aren’t always the most efficient option. XML was designed to be logical, readable, and straightforward—not compact. WPF addresses this shortcoming with BAML (Binary Application Markup Language). BAML is really nothing more than a binary representation of XAML. When you compile a WPF application in Visual Studio, all your XAML files are converted into BAML and that BAML is then embedded as a resource into the final DLL or EXE assembly. BAML is tokenized, which means lengthier bits of XAML are replaced with shorter tokens. Not only is BAML significantly smaller, it’s also optimized in a way that makes it faster to parse at runtime. Most developers won’t worry about the conversion of XAML to BAML because the compiler performs it behind the scenes. However, it is possible to use XAML without compiling it first. This might make sense in scenarios that require some of the user interface to be supplied just in time (for example, pulled out of a database as a block of XAML tags). You’ll see how this works later in this chapter, in the section “Loading and Compiling XAML.”
21
22
CHAPTER 2 ■ XAML
XAML Basics The XAML standard is quite straightforward once you understand a few ground rules: • Every element in a XAML document maps to an instance of a .NET class. The name of the element matches the name of the class exactly. For example, the element instructs WPF to create a Button object. • As with any XML document, you can nest one element inside another. As you’ll see, XAML gives every class the flexibility to decide how it handles this situation. However, nesting is usually a way to express containment—in other words, if you find a Button element inside a Grid element, your user interface probably includes a Grid that contains a Button inside. • You can set the properties of each class through attributes. However, in some situations an attribute isn’t powerful enough to handle the job. In these cases, you’ll use nested tags with a special syntax.
■Tip If you’re completely new to XML, you’ll probably find it easier to review the basics before you tackle XAML. To get up to speed quickly, try the free web-based tutorial at http://www.w3schools.com/xml.
Before continuing, take a look at this bare-bones XAML document, which represents a new blank window (as created by Visual Studio). The lines have been numbered for easy reference: 1 2 3 4 5 6 7 8
This document includes only two elements—the top-level Window element, which represents the entire window, and the Grid, in which you can place all your controls. Although you could use any top-level element, WPF applications rely on just a few: • Window • Page (which is similar to Window, but used for navigable applications) • Application (which defines application resources and startup settings) As in all XML documents, there can only be one top-level element. In the previous example, that means that as soon as you close the Window element with the tag, you end the document. No more content can follow.
CHAPTER 2 ■ XAML
Looking at the start tag for the Window element you’ll find several interesting attributes, including a class name and two XML namespaces (described in the following sections). You’ll also find the three properties shown here: 4
Title="WindowsApplication1" Height="300" Width="300"
Each attribute corresponds to a separate property of the Window class. All in all, this tells WPF to create a window with the caption WindowsApplication1 and to make it 300 by 300 units large.
■Note As you learned in Chapter 1, WPF uses a relative measurement system that isn’t what most Windows developers expect. Rather than letting you set sizes using physical pixels, WPF uses deviceindependent units that can scale to fit different monitor resolutions and are defined as 1/96 of an inch. That means the 300-by-300-unit window in the previous example will be rendered as a 300-by-300-pixel window if your system DPI setting is the standard 96 dpi. However, on a system with a higher system DPI, more pixels will be used. Chapter 1 has the full story.
XAML Namespaces Clearly, it’s not enough to supply just a class name. The XAML parser also needs to know the .NET namespace where this class is located. For example, the Window class could exist in several places—it might refer to the System.Windows.Window class, or it could refer to a Window class in a third-party component, or one you’ve defined in your application. To figure out which class you really want, the XAML parser examines the XML namespace that’s applied to the element. Here’s how it works. In the sample document shown earlier, two namespaces are defined: 2 3
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
■Note XML namespaces are declared using attributes. These attributes can be placed inside any element start tag. However, convention dictates that all the namespaces you need to use in a document should be declared in the very first tag, as they are in this example. Once a namespace is declared, it can be used anywhere in the document.
The xmlns attribute is a specialized attribute in the world of XML that’s reserved for declaring namespaces. This snippet of markup declares two namespaces that you’ll find in every WPF XAML document you create:
23
24
CHAPTER 2 ■ XAML
• http://schemas.microsoft.com/winfx/2006/xaml/presentation is the core WPF namespace. It encompasses all the WPF classes, including the controls you use to build user interfaces. In this example, this namespace is declared without a namespace prefix, so it becomes the default namespace for the entire document. In other words, every element is automatically placed in this namespace unless you specify otherwise. • http://schemas.microsoft.com/winfx/2006/xaml is the XAML namespace. It includes various XAML utility features that allow you to influence how your document is interpreted. This namespace is mapped to the prefix x. That means you can apply it by placing the namespace prefix before the element name (as in ). As you can see, the XML namespace name doesn’t match any particular .NET namespace. There are a couple of reasons the creators of XAML chose this design. By convention, XML namespaces are often URIs (as they are here). These URIs look like they point to a location on the Web, but they don’t. The URI format is used because it makes it unlikely that different organizations will inadvertently create different XML-based languages with the same namespace. Because the domain schemas.microsoft.com is owned by Microsoft, only Microsoft will use it in an XML namespace name. The other reason that there isn’t a one-to-one mapping between the XML namespaces used in XAML and .NET namespaces is because it would significantly complicate your XAML documents. The problem here is that WPF encompasses well over a dozen namespaces (all of which start with System.Windows). If each .NET namespace had a different XML namespace, you’d need to specify the right namespace for each and every control you use, which quickly gets messy. Instead, the creators of WPF chose to combine all of these .NET namespaces into a single XML namespace. This works because within the different .NET namespaces that are a part of WPF, there aren’t any classes that have the same name. The namespace information allows the XAML parser to find the right class. For example, when it looks at the Window and Grid elements, it sees that they are placed in the default WPF namespace. It then searches the corresponding .NET namespaces, until it finds System.Windows.Window and System.Windows.Controls.Grid.
The Code-Behind Class XAML allows you to construct a user interface, but in order to make a functioning application you need a way to connect the event handlers that have your application code. XAML makes this easy using the Class attribute that’s shown here: 1
. If you try to use these values to set the content of an element, you’ll run into trouble because the XAML parser assumes you’re trying to do something else—such as create a nested element. For example, imagine you want to create a button that contains the text . The following markup won’t work: The problem here is that it looks like you’re trying to create an element named Click with an attribute named Me. The solution is to replace the offending characters with entity references—specific codes that the XAML parser will interpret correctly. Table 2-1 lists the character entities you might choose to use. Note that the quotation mark character entity is only required when setting values using an attribute because the quotation mark indicates the beginning and ending of an attribute value. Table 2-1. XML Character Entities
Special Character
Character Entity
Less than ()
>
Ampersand (&)
&
Quotation mark (")
"
Here’s the corrected markup that uses the appropriate character entities:
37
38
CHAPTER 2 ■ XAML
When the XAML parser reads this, it correctly understands that you want to add the text and it passes a string with this content, complete with angled brackets, to the Button.Content property.
■Note This limitation is a XAML detail and it won’t affect you if you want to set the Button.Content property in code. Of course, C# has its own special character (the backslash) that must be escaped in string literals for the same reason.
Special characters aren’t the only stumbling block you’ll run into with XAML. Another issue is whitespace handling. By default, XML collapses all whitespace, which means a long string of spaces, tabs, and hard returns is reduced to a single space. Furthermore, if you add whitespace before or after your element content, this space is ignored completely. You can see this in the EightBall example. The text in the button and the two text boxes is separated from the XAML tags using a hard return and tab to make the markup more readable. However, this extra space doesn’t appear in the user interface. Sometimes this isn’t what you want. For example, you may want to include a series of several spaces in your button text. In this case, you need to use the xml:space="preserve" attribute on your element. The xml:space attribute is a part of the XML standard, and it’s an all-or-nothing setting. Once you switch it on, all the whitespace inside that element is retained. For example, consider this markup: [There is a lot of space inside these quotation marks "
".]
In this example, the text in the text box will include the hard return and tab that appear before the actual text. It will also include the series of spaces inside the text and the hard return that follows the text. If you just want to keep the spaces inside, you’ll need to use this less-readable markup: [There is a lot of space inside these quotation marks "
".]
The trick here is to make sure no whitespace appears between the opening > and your content, or between your content and the closing 0) { string file = e.Args[0];
57
58
CHAPTER 3 ■ THE APPLICATION
if (System.IO.File.Exists(file)) { // Configure the main window. FileViewer win = (FileViewer)Application.Current.MainWindow; win.LoadFile(file); } } } } This method initializes the main window, which is then shown when the App_Startup() method ends. This code assumes that the FileViewer class has a public method (that you’ve added) named LoadFile(). Here’s one possible example, which simply reads (and displays) the text in the file you’ve identified: public partial class FileViewer : Window { ... public void LoadFile(string path) { this.Content = File.ReadAllText(path); this.Title = path; } } You can try an example of this technique with the sample code for this chapter.
■Note If you’re a seasoned Windows Forms programmer, the single line of code in the LoadFile() method looks a little strange. It sets the Content property of the current Window, which determines what the window displays in its client area. Interestingly enough, WPF windows are actually a type of content control (meaning they derive from the ContentControl class). As a result, they can contain (and display) a single object. It’s up to you whether that object is a string, a control, or (more usefully) a panel that can host multiple controls. You’ll learn much more about the WPF content model in the following chapters.
Deriving a Custom Application Class Although the approach shown earlier (instantiating the base Application class and calling the Run() method) works perfectly well, it’s not the pattern that Visual Studio uses when you create a new WPF application. Instead, Visual Studio derives a custom class from the Application class. In a simple application, this approach has no meaningful effect. However, if you’re planning to handle application events, it provides a neater model, because you can place all your event handling code in the Application-derived class.
CHAPTER 3 ■ THE APPLICATION
The model Visual Studio uses for the Application class is essentially the same as the model it uses for the windows. The starting point is a XAML template, which is named App.xaml by default. Here’s what it looks like: As you might remember from Chapter 2, the Class attribute is used in XAML to create a class derived from the element. Thus, this class creates a class that derives from Application, with the name TestApplication.App. (TestApplication is the name of the project, which is the same as the namespace where the class is defined, and App is the name that Visual Studio uses for the custom class that derives from Application. If you want, you can change the class name to something more exciting.) The Application tag not only creates a custom application class, but it also sets the StartupUri property to identify the XAML document that represents the main window. As a result, you don’t need to explicitly instantiate this window using code—the XAML parser will do it for you. As with windows, the application class is defined in two separate portions that are fused together at compile time. The automatically generated portion isn’t visible in your project, but it contains the Main() entry point and the code for starting the application. It looks something like this: using System; using System.Windows; public partial class App : Application { [STAThread()] public static void Main() { TestApplication.App app = new TestApplication.App(); app.InitializeComponent(); app.Run(); } public void InitializeComponent() { this.StartupUri = new Uri("Window1.xaml", System.UriKind.Relative); } } If you’re really interested in seeing the custom application class that the XAML template creates, look for the App.g.cs file in the obj\Debug folder inside your project directory. The only difference between the automatically generated code shown here and a custom application class that you might create on your own is that the automatically generated class
59
60
CHAPTER 3 ■ THE APPLICATION
uses the StartupUri property instead of setting the MainWindow property or passing the main window as a parameter to the Run() method. You’re free to create a custom application class that uses this approach, so long as you use the same URI format. You need to create a relative Uri object that names a XAML document that’s in your project. (This XAML document is compiled and embedded in your application assembly as a BAML resource. The resource name is the name of the original XAML file. In the previous example, the application contains a resource named Window1.xaml with the compiled XAML.)
■Note The URI system you see here is an all-purpose way to refer to resources in your application. You’ll learn more about how it works in Chapter 11.
The second portion of the custom application class is stored in your project in a file like App.xaml.cs. It contains the event handling code you add. Initially, it’s empty: public partial class App : Application { } This file is merged with the automatically generated application code through the magic of partial classes.
Overriding Application Methods Initially, the App.xaml.cs file doesn’t contain any code. Although no code is required, you can add code that handles application events. You have two choices for handling events: you can attach an event handler, or you can override the corresponding protected method. For each application event (as listed in Table 3-2), a corresponding method is called to raise the event. The method name is the same as the event name, except it’s prefixed with the word On, so Startup becomes OnStartup(), Exit becomes OnExit(), and so on. This pattern is extremely common in .NET (and Windows Forms programmers will recognize it well). The only exception is the DispatcherExceptionUnhandled event—there’s no OnDispatcherExceptionUnhandled() method, so you always need to use an event handler. Here’s a custom application class that overrides OnSessionEnding and prevents both the system and itself from shutting down if a flag is set: public partial class App : Application { private bool unsavedData = false; public bool UnsavedData { get { return unsavedData; } set { unsavedData = value; } } protected override void OnStartup(StartupEventArgs e) {
CHAPTER 3 ■ THE APPLICATION
base.OnStartup(e); UnsavedData = true; } protected override void OnSessionEnding(SessionEndingCancelEventArgs e) { base.OnSessionEnding(e); if (UnsavedData) { e.Cancel = true; MessageBox.Show( "The application attempted to be closed as a result of " + e.ReasonSessionEnding.ToString() + ". This is not allowed, as you have unsaved data."); } } } When overriding application methods, it’s a good idea to begin by calling the base class implementation. Ordinarily, the base class implementation does little more than raise the corresponding application event. Obviously, a more sophisticated implementation of this technique wouldn’t use a message box—it would show some sort of confirmation dialog box that would give the user the choice of continuing (and quitting both the application and Windows) or canceling the shutdown. If you choose to handle application events, you don’t need to use delegate code to wire up your event handler. Instead, you can attach it using an attribute in the App.xaml file. For example, if you have this event handler: private void App_DispatcherUnhandledException(object sender, DispatcherUnhandledExceptionEventArgs e) { MessageBox.Show("An unhandled " + e.Exception.GetType().ToString() + " exception was caught and ignored."); e.Handled = true; } you can connect it with this XAML:
61
62
CHAPTER 3 ■ THE APPLICATION
Interacting Between Windows As you’ve seen, the custom application class is a great place to put code that reacts to different application events. There’s one other purpose that an Application class can fill quite nicely: storing references to important windows so one window can access another.
■Tip This technique makes sense when you have a modeless window that lives for a long period of time and might be accessed in several different classes (not just the class that created it). If you’re simply showing a modal dialog box as part of your application, this technique is overkill. In this situation, the window won’t exist for very long, and the code that creates the window is the only code that needs to access it. (To brush up on the difference between modal windows, which interrupt application flow until they’re closed, and modeless windows, which don’t, refer to Chapter 8.)
For example, imagine you want to keep track of all the document windows that your application uses. To that end, you might create a dedicated collection in your custom application class: public partial class App : Application { private List documents = new List(); public List Documents { get { return documents; } set { documents = value; } } } Now, when you create a new document, you simply need to remember to add it to the Documents collection. Here’s an event handler that responds to a button click and does the deed: private void cmdCreate_Click(object sender, RoutedEventArgs e) { Document doc = new Document(); doc.Owner = this; doc.Show(); ((App)Application.Current).Documents.Add(doc); } Alternatively, you could respond to an event like Window.Loaded in the Document class to make sure the document object always registers itself in the Documents collection when it’s created.
CHAPTER 3 ■ THE APPLICATION
■Note This code also sets the Window.Owner property so that all the document windows are displayed “on top” of the main window that creates them. You’ll learn more about the Owner property when you consider windows in detail in Chapter 8.
Now you can use that collection elsewhere in your code to loop over all the documents and use public members. In this case, the Document class includes a custom SetContent() method that updates its display: private void cmdUpdate_Click(object sender, RoutedEventArgs e) { foreach (Document doc in ((App)Application.Current).Documents) { doc.SetContent("Refreshed at " + DateTime.Now.ToLongTimeString() + "."); } } Figure 3-1 demonstrates this application. The actual end result isn’t terribly impressive, but the interaction is worth noting—it demonstrates a safe, disciplined way for your windows to interact through a custom application class. It’s superior to using the Windows property, because it’s strongly typed, and it holds only Document windows (not a collection of all the windows in your application). It also gives you the ability to categorize the windows in another, more useful way—for example, in a Dictionary collection with a key name for easy lookup. In a document-based application, you might choose to index windows in a collection by file name.
Figure 3-1. Allowing windows to interact
63
64
CHAPTER 3 ■ THE APPLICATION
■Note When interacting between windows, don’t forget your object-oriented smarts—always use a layer of custom methods, properties, and events that you’ve added to the window classes. Never expose the fields or controls of a form to other parts of your code. If you do, you’ll quickly wind up with a tightly coupled interface where one window reaches deep into the inner workings of another, and you won’t be able to enhance either class without breaking the murky interdependencies between them.
Single-Instance Applications Ordinarily, you can launch as many copies of a WPF application as you want. In some scenarios, this design makes perfect sense. However, in other cases it’s a problem, particularly when building document-based applications. For example, consider Microsoft Word. No matter how many documents you open (or how you open them), only a single instance of winword.exe is loaded at a time. As you open new documents, they appear in the new windows, but a single application remains in control of all the document windows. This design is the best approach if you want to reduce the overhead of your application, centralize certain features (for example, create a single print queue manager), or integrate disparate windows (for example, offer a feature that tiles all the currently open document windows next to each other). WPF doesn’t provide a native solution for single-instance applications, but you can use several workarounds. The basic technique is to check whether another instance of your application is already running when the Application.Startup event fires. The simplest way to do this is to use a systemwide mutex (a synchronization object provided by the operating system that allows for interprocess communication). This approach is simple but limited—most significantly, there’s no way for the new instance of an application to communicate with the existing instance. This is a problem in a document-based application, because the new instance may need to tell the existing instance to open a specific document, if it’s passed on the command line. (For example, when you double-click a .doc file in Windows Explorer and Word is already running, you expect Word to load the requested file.) This communication is more complex, and it’s usually performed through remoting or Windows Communication Foundation (WCF). A proper implementation needs to include a way to discover the remoting server and use it to transfer command-line arguments. But the simplest approach, and the one that’s currently recommended by the WPF team, is to use the built-in support that’s provided in Windows Forms and originally intended for Visual Basic applications. This approach handles the messy plumbing behind the scenes. So, how can you use a feature that’s designed for Windows Forms and Visual Basic to manage a WPF application in C#? Essentially, the old-style application class acts as a wrapper for your WPF application class. When your application is launched, you’ll create the old-style application class, which will then create the WPF application class. The old-style application class handles the instance management, while the WPF application class handles the real application. Figure 3-2 shows how these parts interact.
CHAPTER 3 ■ THE APPLICATION
WindowsFormsApplicationBase
Application
(in Microsoft.VisualBasic.ApplicationServices)
(in System.Windows)
Window Create
OnStartup()
Create
OnStartup()
OnStartupNextInstance()
Activate
LoadDocument() (custom method)
Window
Create
Figure 3-2. Wrapping the WPF application with a WindowsFormsApplicationBase The first step to use this approach is to add a reference to the Microsoft.VisualBasic.dll assembly and derive a custom class from the Microsoft.VisualBasic.ApplicationServices. WindowsFormsApplicationBase class. This class provides three important members that you use for instance management: • The IsSingleInstance property enables a single-instance application. You set this property to true in the constructor. • The OnStartup() method is triggered when the application starts. You handle this event and create the WPF application object at this point. • The OnStartupNextInstance() method is triggered when another instance of the application starts up. This method provides access to the command-line arguments. At this point, you’ll probably call a method in your WPF application class to show a new window but not create another application object. Here’s the code for the custom class that’s derived from WindowsFormsApplicationBase: public class SingleInstanceApplicationWrapper : Microsoft.VisualBasic.ApplicationServices.WindowsFormsApplicationBase { public SingleInstanceApplicationWrapper() { // Enable single-instance mode. this.IsSingleInstance = true; } // Create the WPF application class. private WpfApp app; protected override bool OnStartup( Microsoft.VisualBasic.ApplicationServices.StartupEventArgs e) { app = new WpfApp(); app.Run(); return false; }
65
66
CHAPTER 3 ■ THE APPLICATION
// Direct multiple instances. protected override void OnStartupNextInstance( Microsoft.VisualBasic.ApplicationServices.StartupNextInstanceEventArgs e) { if (e.CommandLine.Count > 0) { app.ShowDocument(e.CommandLine[0]); } } } When the application starts, this class creates an instance of WpfApp, which is a custom WPF application class (a class that derives from System.Windows.Application). The WpfApp class includes some startup logic that shows a main window, along with a custom ShowDocument() window that loads a document window for a given file. Every time a file name is passed to SingleInstanceApplicationWrapper through the command line, SingleInstanceApplicationWrapper calls WpfApp.ShowDocument(). Here’s the code for the App class: public class WpfApp : System.Windows.Application { protected override void OnStartup(System.Windows.StartupEventArgs e) { base.OnStartup(e); WpfApp.current = this; // Load the main window. DocumentList list = new DocumentList(); this.MainWindow = list; list.Show(); // Load the document that was specified as an argument. if (e.Args.Length > 0) ShowDocument(e.Args[0]); } public void ShowDocument(string filename) { try { Document doc = new Document(); doc.LoadFile(filename); doc.Owner = this.MainWindow; doc.Show(); // If the application is already loaded, it may not be visible. // This attempts to give focus to the new window. doc.Activate(); } catch
CHAPTER 3 ■ THE APPLICATION
{ MessageBox.Show("Could not load document."); } } } The only missing detail now (aside from the DocumentList and Document windows) is the entry point for the application. Because the application needs to create the Singl-InstanceApplicationWrapper class before the App class, the application needs to start with a traditional Main() method, rather than an App.xaml file. Here’s the code you need: public class Startup { [STAThread] public static void Main(string[] args) { SingleInstanceApplicationWrapper wrapper = new SingleInstanceApplicationWrapper(); wrapper.Run(args); } } These three classes—SingleInstanceApplicationWrapper, WpfApp, and Startup—form the basis for a single-instance WPF application. Using these bare-bones, it’s possible to create a more sophisticated example. For example, the downloadable code for this chapter modifies the WpfApp class so it maintains a list of open documents (as demonstrated earlier). Using WPF data binding (a feature described in Chapter 16), the DocumentList window displays the currently open documents. Figure 3-3 shows an example with three open documents. Finally, the SingleInstanceApplication example includes a FileRegistrationHelper class that registers a file extension using the classes in the Microsoft.Win32 namespace: string extension = ".testDoc"; string title = "SingleInstanceApplication"; string extensionDescription = "A Test Document"; FileRegistrationHelper.SetFileAssociation( extension, title + "." + extensionDescription); This code needs to be executed only once. After the registration is in place, every time you double-click a file with the extension .testDoc, the SingleInstanceApplication is started, and the file is passed as a command-line argument. If the SingleInstanceApplication is already running, the SingleInstanceApplicationWrapper.OnStartupNextInstance() method is called, and the new document is loaded by the existing application.
■Note Single-instance application support will eventually make its way to WPF in a future version. For now, this workaround provides the same functionality with only a little more work required.
67
68
CHAPTER 3 ■ THE APPLICATION
Figure 3-3. A single-instance application with a central window
WINDOWS VISTA AND UAC File registration is a task that’s usually performed by a setup program. One problem with including it in your application code is that it requires elevated permissions that the user running the application might not have. This is particularly a problem with the User Account Control (UAC) feature in Windows Vista. To run this registry-updating code shown in the previous example under Windows Vista, you’ll need to force your application to run with administrator privileges. If you’re running the application inside Visual Studio, that means you need to run Visual Studio with administrator privileges (by right-clicking the Visual Studio icon and choosing Run As Administrator). If you’re running the application outside Visual Studio, you’ll need configure the same behavior through the application properties (right-click, choose Properties, and switch to the Compatibility tab to find the same setting). An alternate approach is to prepare a manifest for the application. The manifest must have the same name as the executable, plus the extension .manifest, as in SingleInstanceApplication.exe.manifest. The content of this file is the relatively simple block of XML shown here:
CHAPTER 3 ■ THE APPLICATION
The next time you run the application, you’ll receive a UAC prompt asking you to confirm that you want to give the application expanded access to your computer. It’s possible to embed the manifest inside your executable. Currently, Visual Studio doesn’t have built-in support for this feature, but you can use the mt.exe tool included with .NET. You can download a detailed white paper about developing with UAC in mind at http://tinyurl.com/hqmh5.
Multithreading Multithreading is the art of executing more than one piece of code at once. The goal of multithreading is usually to create a more responsive interface—one that doesn’t freeze up while it’s in the midst of other work—although you can also use multithreading to take better advantage of dual-core CPUs when executing a processor-intensive algorithm or to perform other work during a high-latency operation (for example, to perform some calculations while waiting for a response from a web service). Early in the design of WPF, the creators considered a new threading model. This model— called thread rental—allowed user interface objects to be accessed on any thread. To reduce the cost of locking, groups of related objects could be grouped under a single lock (called a context). Unfortunately, this design introduced additional complexity for single-threaded applications (which needed to be context-aware) and made it more difficult to interoperate with legacy code (like the Win32 API). Ultimately, the plan was abandoned. The result is that WPF supports a single-threaded apartment model that’s very much like the one used in Windows Forms applications. It has a few core rules: • WPF elements have thread affinity. The thread that creates them owns them, and other threads can’t interact with them directly. (An element is a WPF object that’s displayed in a window.) • WPF objects that have thread affinity derive from DispatcherObject at some point in their class hierarchy. DispatcherObject includes a small set of members that allow you to verify whether code is executing on the right thread to use a specific object and (if not) switch it over. • In practice, one thread runs your entire application and owns all WPF objects. Although you could use separate threads to show separate windows, this design is rare. In the following sections, you’ll explore the DispatcherObject class and learn the simplest way to perform an asynchronous operation in a WPF application.
69
70
CHAPTER 3 ■ THE APPLICATION
The Dispatcher A dispatcher manages the work that takes place in a WPF application. The dispatcher owns the application thread and manages a queue of work items. As your application runs, the dispatcher accepts new work requests and executes one at a time. Technically, a dispatcher is created the first time you instantiate a class that derives from DispatcherObject on a new thread. If you create separate threads and use them to show separate windows, you’ll wind up with more than one dispatcher. However, most applications keep things simple and stick to one user interface thread and one dispatcher. They then use multithreading to manage data operations and other background tasks.
■Note The dispatcher is an instance of the System.Windows.Threading.Dispatcher class. All the dispatcherrelated objects are also found in the small System.Windows.Threading namespace, which is new to WPF. (The core threading classes that have existed since .NET 1.0 are found in System.Threading.)
You can retrieve the dispatcher for the current thread using the static Dispatcher.CurrentDispatcher property. Using this Dispatcher object, you can attach event handlers that respond to unhandled exceptions or respond when the dispatcher shuts down. You can also get a reference to the System.Threading.Thread that the dispatcher controls, shut down the dispatcher, or marshal code to the correct thread (a technique you’ll see in the next section).
The DispatcherObject Most of the time, you won’t interact with a dispatcher directly. However, you’ll spend plenty of time using instances of DispatcherObject, because every visual WPF object derives from this class. A DispatcherObject is simply an object that’s linked to a dispatcher—in other words, an object that’s bound to the dispatcher’s thread. The DispatcherObject introduces just three members, as listed in Table 3-3. Table 3-3. Members of the DispatcherObject Class
Name
Description
Dispatcher
Returns the dispatcher that’s managing this object
CheckAccess()
Returns true if the code is on the right thread to use the object; returns false otherwise
VerifyAccess()
Does nothing if the code is on the right thread to use the object; throws an InvalidOperationException otherwise
WPF objects call VerifyAccess() frequently to protect themselves. They don’t call VerifyAccess() in response to every operation (because that would impose too great a performance overhead), but they do call it often enough that you’re unlikely to use an object from the wrong thread for very long.
CHAPTER 3 ■ THE APPLICATION
For example, the following code responds to a button click by creating a new System.Threading.Thread object. It then uses that thread to launch a small bit of code that changes a text box in the current window. private void cmdBreakRules_Click(object sender, RoutedEventArgs e) { Thread thread = new Thread(UpdateTextWrong); thread.Start(); } private void UpdateTextWrong() { // Simulate some work taking place with a five-second delay. Thread.Sleep(TimeSpan.FromSeconds(5)); txt.Text = "Here is some new text."; } This code is destined to fail. The UpdateTextWrong() method will be executed on a new thread, and that thread isn’t allowed to access WPF objects. In this case, the TextBox object catches the violation by calling VerifyAccess(), and an InvalidOperationException is thrown. To correct this code, you need to get a reference to the dispatcher that owns the TextBox object (which is the same dispatcher that owns the window and all the other WPF objects in the application). Once you have access to that dispatcher, you can call Dispatcher.BeginInvoke() to marshal some code to the dispatcher thread. Essentially, BeginInvoke() schedules your code as a task for the dispatcher. The dispatcher then executes that code. Here’s the corrected code: private void cmdFollowRules_Click(object sender, RoutedEventArgs e) { Thread thread = new Thread(UpdateTextRight); thread.Start(); } private void UpdateTextRight() { // Simulate some work taking place with a five-second delay. Thread.Sleep(TimeSpan.FromSeconds(5)); // Get the dispatcher from the current window. this.Dispatcher.BeginInvoke(DispatcherPriority.Normal, (ThreadStart) delegate() { txt.Text = "Here is some new text."; } ); } The Dispatcher.BeginInvoke() method takes two parameters. The first indicates the priority of the task. In most cases, you’ll use DispatcherPriority.Normal, but you can also use a lower pri-
71
72
CHAPTER 3 ■ THE APPLICATION
ority if you have a task that doesn’t need to be completed immediately and that should be kept on hold until the dispatcher has nothing else to do. For example, this might make sense if you need to display a status message about a long-running operation somewhere in your user interface. You can use DispatcherPriority.ApplicationIdle to wait until the application is finished all other work or the even more laid-back DispatcherPriority.SystemIdle to wait until the entire system is at rest and the CPU is idle. You can also use an above-normal priority to get the dispatcher’s attention right away. However, it’s recommended that you leave higher priorities to input messages (such as key presses). These need to be handled nearly instantaneously, or the application will feel sluggish. On the other hand, adding a few milliseconds of extra time to a background operation won’t be noticeable, so a priority of DispatcherPriority.Normal makes more sense in this situation. The second BeginInvoke() parameter is a delegate that points to the method with the code you want to execute. This could be a method somewhere else in your code, or you can use an anonymous method to define your code inline (as in this example). The inline approach works well for simple operations, like this single-line update. However, if you need to use a more complex process to update the user interface, it’s a good idea to factor this code into a separate method.
■Note The BeginInvoke() method also has a return value, which isn’t used in the earlier example. BeginInvoke() returns a DispatcherOperation object, which allows you to follow the status of your marshaling operation and determine when your code has actually been executed. However, the DispatcherOperation is rarely useful, because the code you pass to BeginInvoke() should take very little time.
Remember, if you’re performing a time-consuming background operation, you need to perform this operation on a separate thread and then marshal its result to the dispatcher thread (at which point you’ll update the user interface or change a shared object). It makes no sense to perform your time-consuming code in the method that you pass to BeginInvoke(). For example, this code works but is impractical: private void UpdateTextRight() { // Get the dispatcher from the current window. this.Dispatcher.BeginInvoke(DispatcherPriority.Normal, (ThreadStart) delegate() { // Simulate some work taking place. Thread.Sleep(TimeSpan.FromSeconds(5)); txt.Text = "Here is some new text."; } ); } The problem here is that all the work takes place on the dispatcher thread. That means this code ties up the dispatcher in the same way a non-multithreaded application would.
CHAPTER 3 ■ THE APPLICATION
■Note The dispatcher also provides an Invoke() method. Like BeginInvoke(), Invoke() marshals the code you specify to the dispatcher thread. But unlike BeginInvoke(), Invoke() stalls your thread until the dispatcher executes your code. You might use Invoke() if you need to pause an asynchronous operation until the user has supplied some sort of feedback. For example, you could call Invoke() to run a snippet of code that shows an OK/Cancel dialog box. After the user clicks a button and your marshaled code completes, the Invoke() method will return, and you can act upon the user’s response.
The BackgroundWorker You can perform asynchronous operations in many ways. You’ve already seen one no-frills approach—creating a new System.Threading.Thread object by hand, supplying your asynchronous code, and launching it with the Thread.Start() method. This approach is powerful, because the Thread object doesn’t hold anything back. You can create dozens of threads at will, set their priorities, control their status (for example, pausing, resuming, and aborting them), and so on. However, this approach is also a bit dangerous. If you access shared data, you need to use locking to prevent subtle errors. If you create threads frequently or in large numbers, you’ll generate additional, unnecessary overhead. The techniques to write good multithreading code—and the .NET classes you’ll use— aren’t WPF-specific. If you’ve written multithreaded code in a Windows Forms application, you can use the same techniques in the WPF world. In the remainder of this chapter, you’ll consider one of the simplest and safest approaches: the System.ComponentModel. BackgroundWorker component.
■Tip To see several different approaches, ranging from simple to more complex, you may want to refer to my book Programming .NET 2.0 Windows Forms and Custom Controls in C# (Apress, 2005).
The BackgroundWorker was introduced in .NET 2.0 to simplify threading considerations in Windows Forms applications. However, the BackgroundWorker is equally at home in WPF. The BackgroundWorker component gives you a nearly foolproof way to run a time-consuming task on a separate thread. It uses the dispatcher behind the scenes and abstracts away the marshaling issues with an event-based model. As you’ll see, the BackgroundWorker also supports two frills: progress events and cancel messages. In both cases the threading details are hidden, making for easy coding.
■Note The BackgroundWorker is perfect if you have a single asynchronous task that runs in the background from start to finish (with optional support for progress reporting and cancellation). If you have something else in mind—for example, an asynchronous task that runs throughout the entire life of your application or an asynchronous task that communicates with your application while it does its work, you’ll need to design a customized solution using .NET’s threading support.
73
74
CHAPTER 3 ■ THE APPLICATION
A Simple Asynchronous Operation To try the BackgroundWorker, it helps to consider a sample application. The basic ingredient for any test is a time-consuming process. The following example uses a common algorithm for finding prime numbers in a given range called the sieve of Eratosthenes, which was invented by Eratosthenes himself in about 240 BC. With this algorithm, you begin by making a list of all the integers in a range of numbers. You then strike out the multiples of all primes less than or equal to the square root of the maximum number. The numbers that are left are the primes. In this example, I won’t go into the theory that proves the sieve of Eratosthenes works or show the fairly trivial code that performs it. (Similarly, don’t worry about optimizing it or comparing it against other techniques.) However, you will see how to perform the sieve of Eratosthenes algorithm asynchronously. The full code is available with the online examples for this chapter. It takes this form: public class Worker { public static int[] FindPrimes(int fromNumber, int toNumber) { // Find the primes between fromNumber and toNumber, // and return them as an array of integers. } } The FindPrimes() method takes two parameters that delimit a range of numbers. The code then returns an integer array with all the prime numbers that occur in that range. Figure 3-4 shows the example we’re building. This window allows the user to choose the range of numbers to search. When the user clicks Find Primes, the search begins, but it takes place in the background. When the search is finished, the list of prime numbers appears in the list box.
Creating the BackgroundWorker To use the BackgroundWorker, you begin by creating an instance. Here, you have two options: • You can create the BackgroundWorker in your code and attach all the event handlers programmatically. • You can declare the BackgroundWorker in your XAML. The advantage of this approach is that you can hook up your event handlers using attributes. Because the BackgroundWorker isn’t a visible WPF element, you can’t place it just anywhere. Instead you need to declare it as a resource for your window. (You’ll learn all about resources in Chapter 11.) Both approaches are equivalent. The downloadable sample uses the second approach. The first step is to make the System.ComponentModel namespace accessible in your XAML document through a namespace import. To do this, you need to use the namespace mapping technique you learned about in Chapter 2:
CHAPTER 3 ■ THE APPLICATION
Figure 3-4. A completed prime number search Now you can create an instance of the BackgroundWorker in the Window.Resources collection. When doing this, you need to supply a key name so the object can be retrieved later. In this example, the key name is backgroundWorker: The advantage of declaring the BackgroundWorker in the Window.Resources section is that you can set its properties and attach its event handlers using attributes. For example, here’s the BackgroundWorker tag you’ll end up with at the end of this example, which enables support for progress notification and cancellation and attaches event handlers to the DoWork, ProgressChanged, and RunWorkerCompleted events:
75
76
CHAPTER 3 ■ THE APPLICATION
To get access to this resource in your code, you need to pull it out of the Resources collection. In this example, the window performs this step in its constructor so that all your event handling code can access it more easily: private BackgroundWorker backgroundWorker; public BackgroundWorkerTest() { InitializeComponent(); backgroundWorker = ((BackgroundWorker)this.FindResource("backgroundWorker")); }
■Note You’ll learn much more about the Resources collection in Chapter 11.
Running the BackgroundWorker The first step to using the BackgroundWorker with the prime number search example is to create a custom class that allows you to transmit the input parameters to the BackgroundWorker. When you call BackgroundWorker.RunWorkerAsync(), you can supply any object, which will be delivered to the DoWork event. However, you can supply only a single object, so you need to wrap the to and from numbers into one class, as shown here: public class FindPrimesInput { private int from; public int From { get { return from; } set { from = value; } } private int to; public int To { get { return to; } set { to = value; } } public FindPrimesInput(int from, int to) { From = from; To = to; } }
CHAPTER 3 ■ THE APPLICATION
To start the BackgroundWorker on its way, you need to call the BackgroundWorker. RunWorkerAsync() method and pass in the FindPrimesInput object. Here’s the code that does this when the user clicks the Find Primes button: private void cmdFind_Click(object sender, RoutedEventArgs e) { // Disable this button and clear previous results. cmdFind.IsEnabled = false; cmdCancel.IsEnabled = true; lstPrimes.Items.Clear(); // Get the search range. int from, to; if (!Int32.TryParse(txtFrom.Text, out from)) { MessageBox.Show("Invalid From value."); return; } if (!Int32.TryParse(txtTo.Text, out to)) { MessageBox.Show("Invalid To value."); return; } // Start the search for primes on another thread. FindPrimesInput input = new FindPrimesInput(from, to); backgroundWorker.RunWorkerAsync(input); } When the BackgroundWorker begins executing, it grabs a free thread from the CLR thread pool and then fires the DoWork event from this thread. You handle the DoWork event and begin your time-consuming task. However, you need to be careful not to access shared data (such as fields in your window class) or user interface objects. Once the work is complete, the BackgroundWorker fires the RunWorkerCompleted event to notify your application. This event fires on the dispatcher thread, which allows you to access shared data and your user interface, without incurring any problems. Once the BackgroundWorker acquires the thread, it fires the DoWork event. You can handle this event to call the Worker.FindPrimes() method. The DoWork event provides a DoWorkEventArgs object, which is the key ingredient for retrieving and returning information. You retrieve the input object through the DoWorkEventArgs.Argument property and return the result by setting the DoWorkEventArgs.Result property. private void backgroundWorker_DoWork(object sender, DoWorkEventArgs e) { // Get the input values. FindPrimesInput input = (FindPrimesInput)e.Argument; // Start the search for primes and wait.
77
78
CHAPTER 3 ■ THE APPLICATION
// This is the time-consuming part, but it won't freeze the // user interface because it takes place on another thread. int[] primes = Worker.FindPrimes(input.From, input.To); // Return the result. e.Result = primes; } Once the method completes, the BackgroundWorker fires the RunWorkerCompleted-EventArgs on the dispatcher thread. At this point, you can retrieve the result from the RunWorkerCompletedEventArgs.Result property. You can then update the interface and access window-level variables without worry. private void backgroundWorker_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e) { if (e.Error != null) { // An error was thrown by the DoWork event handler. MessageBox.Show(e.Error.Message, "An Error Occurred"); } else { int[] primes = (int[])e.Result; foreach (int prime in primes) { lstPrimes.Items.Add(prime); } } cmdFind.IsEnabled = true; cmdCancel.IsEnabled = false; progressBar.Value = 0; } Notice that you don’t need any locking code, and you don’t need to use the Dispatcher. BeginInvoke() method. The BackgroundWorker takes care of these issues for you. Behind the scenes, the BackgroundWorker uses a few multithreading classes that were introduced in .NET 2.0, including AsyncOperationManager, AsyncOperation, and SynchronizationContext. Essentially, the BackgroundWorker uses AsyncOperationManager to manage the background task. The AsyncOperationManager has some built-in intelligence— namely, it’s able to get the synchronization context for the current thread. In a Windows Forms application, the AsyncOperationManager gets a WindowsFormsSynchronizationContext object, whereas a WPF application gets a DispatcherSynchronizationContext object. Conceptually, these classes do the same job, but their internal plumbing is different.
CHAPTER 3 ■ THE APPLICATION
Tracking Progress The BackgroundWorker also provides built-in support for tracking progress, which is useful for keeping the client informed about how much work has been completed in a long-running task. To add support for progress, you need to first set the BackgroundWorker.WorkerReportsProgress property to true. Actually, providing and displaying the progress information is a two-step affair. First, the DoWork event handling code needs to call the BackgroundWorker.ReportProgresss() method and provide an estimated percent complete (from 0% to 100%). You can do this as little or as often as you like. Every time you call ReportProgress(), the BackgroundWorker fires the ProgressChanged event. You can react to this event to read the new progress percentage and update the user interface. Because the ProgressChanged event fires from the user interface thread, there’s no need to use Dispatcher.BeginInvoke(). The FindPrimes() method reports progress in 1% increments, using code like this: int iteration = list.Length / 100; for (int i = 0; i < list.Length; i++) { ... // // // // if
Report progress only if there is a change of 1%. Also, don't bother performing the calculation if there isn't a BackgroundWorker or if it doesn't support progress notifications. ((i % iteration == 0) && (backgroundWorker != null) && backgroundWorker.WorkerReportsProgress)
{ backgroundWorker.ReportProgress(i / iteration); } } Once you’ve set the BackgroundWorker.WorkerReportsProgress property, you can respond to these progress notifications by handing the ProgressChanged event. In this example, a progress bar is updated accordingly: private void backgroundWorker_ProgressChanged(object sender, ProgressChangedEventArgs e) { progressBar.Value = e.ProgressPercentage; }
79
80
CHAPTER 3 ■ THE APPLICATION
Figure 3-5 shows the progress meter while the task is in progress.
Figure 3-5. Tracking progress for an asynchronous task
Supporting Cancellation It’s just as easy to add support for canceling a long-running task with the BackgroundWorker. The first step is to set the BackgroundWorker.WorkerSupportsCancellation property to true. To request a cancellation, your code needs to call the BackgroundWorker.CancelAsync() method. In this example, the cancellation is requested when a Cancel button is clicked: private void cmdCancel_Click(object sender, RoutedEventArgs e) { backgroundWorker.CancelAsync(); } Nothing happens automatically when you call CancelAsync(). Instead, the code that’s performing the task needs to explicitly check for the cancel request, perform any required cleanup, and return. Here’s the code in the FindPrimes() method that checks for cancellation requests just before it reports progress: for (int i = 0; i < list.Length; i++) { ... if ((i % iteration) && (backgroundWorker != null)) { if (backgroundWorker.CancellationPending) { // Return without doing any more work.
CHAPTER 3 ■ THE APPLICATION
return; } if (backgroundWorker.WorkerReportsProgress) { backgroundWorker.ReportProgress(i / iteration); } } } The code in your DoWork event handler also needs to explicitly set the DoWorkEventArgs.Cancel property to true to complete the cancellation. You can then return from that method without attempting to build up the string of primes. private void backgroundWorker_DoWork(object sender, DoWorkEventArgs e) { FindPrimesInput input = (FindPrimesInput)e.Argument; int[] primes = Worker.FindPrimes(input.From, input.To, backgroundWorker); if (backgroundWorker.CancellationPending) { e.Cancel = true; return; } // Return the result. e.Result = primes; } Even when you cancel an operation, the RunWorkerCompleted event still fires. At this point, you can check whether the task was cancelled and handle it accordingly. private void backgroundWorker_RunWorkerCompleted(object sender, RunWorkerCompletedEventArgs e) { if (e.Cancelled) { MessageBox.Show("Search cancelled."); } else if (e.Error != null) { // An error was thrown by the DoWork event handler. MessageBox.Show(e.Error.Message, "An Error Occurred"); } else { int[] primes = (int[])e.Result; foreach (int prime in primes)
81
82
CHAPTER 3 ■ THE APPLICATION
{ lstPrimes.Items.Add(prime); } } cmdFind.IsEnabled = true; cmdCancel.IsEnabled = false; progressBar.Value = 0; } Now the BackgroundWorker component allows you to start a search and end it prematurely.
The Last Word In this chapter, you took a quick look at the WPF application model. To manage a simple WPF application, you need to do nothing more than create an instance of the Application class and call the Run() method. However, professional programmers usually go further and derive a custom class from the Application class. And as you saw, this custom class is an ideal tool for handling application events and an ideal place to track the forms in your application. Finally, you considered the multithreading considerations of WPF applications, which are essentially the same as the considerations for any other type of Windows application. You haven’t quite plumbed the full reaches of the Application class—there’s still a Resources collection to consider, where you can define objects you want to reuse throughout your application, like styles that can be applied to controls in multiple windows. However, it’s safe to leave these details to Chapter 11, when you explore the WPF resource model in more detail. Instead, in the next chapter you’ll consider how controls are organized into realistic windows using the WPF layout panels.
CHAPTER
4
■■■
Layout H
alf the battle in any user interface design is organizing the content in a way that’s attractive, practical, and flexible. But the real challenge is making sure that your layout can adapt itself gracefully to different window sizes. In WPF, you shape layout using different containers. Each container has its own layout logic—some stack elements, others arrange them in a grid of invisible cells, and so on. If you’ve programmed with Windows Forms, you’ll be surprised to find that coordinate-based layout is strongly discouraged in WPF. Instead, the emphasis is on creating more flexible layouts that can adapt to changing content, different languages, and a variety of window sizes. For most developers moving to WPF, the new layout system is a great surprise—and the first real challenge. In this chapter, you’ll see how the WPF layout model works, and you’ll begin using the basic layout containers. You’ll also consider several common layout examples—everything from a basic dialog box to a resizable split window—in order to learn the fundamentals of WPF layout.
Understanding Layout in WPF The WPF layout model represents a dramatic shift in the way Windows developers approach user interfaces. In order to understand the new WPF layout model, it helps to take a look at what’s come before. In .NET 1.x, the layout system was fairly primitive. Controls were fixed in place using hard-coded coordinates. The only saving grace was anchoring and docking—two features that allowed controls to move or resize themselves along with their container. Anchoring and docking were great for creating simple resizable windows—for example, keeping an OK and Cancel button stuck to the bottom-right corner of a window, or allowing a TreeView to expand to fill an entire form—but they couldn’t handle serious layout challenges. For example, anchoring and docking couldn’t implement bi-pane proportional resizing (dividing extra space equally among two regions). They also weren’t much help if you had highly dynamic content, such as a label that might expand to hold more text than anticipated, causing it to overlap other nearby controls. .NET 2.0 filled the gaps with two new layout containers: the FlowLayoutPanel and TableLayoutPanel. Using these controls, you could create more sophisticated weblike interfaces. Both layout containers allowed their contained controls to grow and bump other controls out of the way. This made it easier to deal with dynamic content, create modular interfaces, and localize your application. However, the layout panels still felt like an add-on to 83
84
CHAPTER 4 ■ LAYOUT
the core Windows Forms layout system, which used fixed coordinates. The layout panels were an elegant solution, but you could see the duct tape holding it all together. WPF introduces a new layout system that’s heavily influenced by the developments in Windows Forms. This system reverses the .NET 2.0 model (coordinate-based layout with optional flow-based layout panels) by making flow-based layout the standard and giving only rudimentary support for coordinate-based layout. The benefits of this shift are enormous. Developers can now create resolution-independent, size-independent interfaces that scale well on different monitors, adjust themselves when content changes, and handle the transition to other languages effortlessly. However, before you can take advantage of these changes, you’ll need to start thinking about layout a little differently.
The WPF Layout Philosophy A WPF window can only hold a single element. To fit in more than one element and create a more practical user interface, you need to place a container in your window and then add other elements to that container.
■Note This limitation stems from the fact that the Window class is derived from ContentControl, which you’ll study more closely in Chapter 5.
In WPF, layout is determined by the container that you use. Although there are several containers to choose from, the “ideal” WPF window follows a few key principles: • Elements (like controls) should not be explicitly sized. Instead, they grow to fit their content. For example, a button expands as you add more text. You can limit controls to acceptable sizes by setting a maximum and minimum size. • Elements do not indicate their position with screen coordinates. Instead, they are arranged by their container based on their size, order, and (optionally) other information that’s specific to the layout container. If you need to add whitespace between elements, you use the Margin property.
■Tip Hard-coded sizes and positions are evil because they limit your ability to localize your interface, and they make it much more difficult to deal with dynamic content.
• Layout containers “share” the available space among their children. They attempt to give each element its preferred size (based on its content) if the space is available. They can also distribute extra space to one or more children. • Layout containers can be nested. A typical user interface begins with the Grid, WPF’s most capable container, and contains other layout containers that arrange smaller groups of elements, such as captioned text boxes, items in a list, icons on a toolbar, a column of buttons, and so on.
CHAPTER 4 ■ LAYOUT
Although there are exceptions to these rules, they reflect the overall design goals of WPF. In other words, if you follow these guidelines when you build a WPF application, you’ll create a better, more flexible user interface. If you break these rules, you’ll end up with a user interface that isn’t well-suited to WPF and is much more difficult to maintain.
The Layout Process WPF layout takes place in two stages: a measure stage and an arrange stage. In the measure stage, the container loops through its child elements and asks them to provide their preferred size. In the arrange stage, the container places the child elements in the appropriate position. Of course, an element can’t always get its preferred size—sometimes the container isn’t large enough to accommodate it. In this case, the container must truncate the offending element to fit the visible area. As you’ll see, you can often avoid this situation by setting a minimum window size.
■Note Layout containers don’t provide any scrolling support. Instead, scrolling is provided by a specialized content control—the ScrollViewer—that can be used just about anywhere. You’ll learn about the ScrollViewer in Chapter 5.
The Layout Containers All the WPF layout containers are panels that derive from the abstract System.Windows. Controls.Panel class (see Figure 4-1). The Panel class adds a small set of members, including the three public properties that are detailed in Table 4-1.
DispatcherObject
Legend Abstract Class
DependencyObject Concrete Class Visual
UIElement
FrameworkElement
Panel
Figure 4-1. The hierarchy of the Panel class
85
86
CHAPTER 4 ■ LAYOUT
Table 4-1. Public Properties of the Panel Class
Name
Description
Background
The brush that’s used to paint the panel background. You must set this property to a non-null value if you want to receive mouse events. (If you want to receive mouse events but you don’t want to display a solid background, just set the background color to Transparent.) You’ll learn more about basic brushes in Chapter 7 (and more advanced brushes in Chapter 13).
Children
The collection of items that’s stored in the panel. This is the “first level” of items—in other words, these items may themselves contain more items.
IsItemsHost
A Boolean value that’s true if the panel is being used to show the items that are associated with an ItemsControl (such as the nodes in a TreeView or the list entries in a ListBox). Most of the time you won’t even be aware that a list control is using a behind-the-scenes panel to manage the layout of its items. However, this detail becomes more important if you want to create a customized list that lays out children in a different way (for example, a ListBox that tiles images). You’ll use this technique in Chapter 17.
■Note The Panel class also has a bit of internal plumbing you can use if you want to create your own layout container. Most notably, you can override the MeasureOverride() and ArrangeOverride() methods inherited from FrameworkElement to change the way the panel handles the measure stage and the arrange stage when organizing its child elements. You’ll learn how to create a custom panel in Chapter 24.
On its own, the base Panel class is nothing but a starting point for other more specialized classes. WPF provides a number of Panel-derived classes that you can use to arrange layout. The most fundamental of these are listed in Table 4-2. As with all WPF controls and most visual elements, these classes are found in the System.Windows.Controls namespace. Table 4-2. Core Layout Panels
Name
Description
StackPanel
Places elements in a horizontal or vertical stack. This layout container is typically used for small sections of a larger, more complex window.
WrapPanel
Places elements in a series of wrapped lines. In horizontal orientation, the WrapPanel lays items out in a row from left to right and then onto subsequent lines. In vertical orientation, the WrapPanel lays out items in a top-to-bottom column and then uses additional columns to fit the remaining items.
DockPanel
Aligns elements against an entire edge of the container.
Grid
Arranges elements in rows and columns according to an invisible table. This is one of the most flexible and commonly used layout containers.
UniformGrid
Places elements in an invisible table but forces all cells to have the same size. This layout container is used infrequently.
Canvas
Allows elements to be positioned absolutely using fixed coordinates. This layout container is the most similar to traditional Windows Forms, but it doesn’t provide anchoring or docking features. As a result, it’s an unsuitable choice for a resizable window unless you’re willing to do a fair bit of work.
CHAPTER 4 ■ LAYOUT
Along with these core containers, there are several more specialized panels that you’ll encounter in various controls. These include panels that are dedicated to holding the child items of a particular control—such as TabPanel (the tabs in a TabControl), ToolbarPanel (the buttons in a Toolbar), and ToolbarOverflowPanel (the commands in a Toolbar’s overflow menu). There’s also a VirtualizingStackPanel, which databound list controls use to minimize their overhead, and an InkCanvas, which is similar to the Canvas but has support for handling stylus input on the TabletPC. (For example, depending on the mode you choose, the InkCanvas supports “drawing” with the pointer to select onscreen elements. And although it’s a little counterintuitive, you can use the InkCanvas with an ordinary computer and a mouse.)
Simple Layout with the StackPanel The StackPanel is one of the simplest layout containers. It simply stacks its children in a single row or column. For example, consider this window, which contains a stack of three buttons: A Button Stack Button 1 Button 2 Button 3 Button 4 Figure 4-2 shows the window that results.
Figure 4-2. The StackPanel in action
87
88
CHAPTER 4 ■ LAYOUT
By default, a StackPanel arranges elements from top to bottom, making each one as tall as is necessary to display its content. In this example, that means the labels and buttons are sized just large enough to comfortably accommodate the text inside. All elements are stretched to the full width of the StackPanel, which is the width of the window. If you widen the window, the StackPanel widens as well, and the buttons stretch themselves to fit. The StackPanel can also be used to arrange elements horizontally by setting the Orientation property: Now elements are given their minimum width (wide enough to fit their text) and are stretched to the full height of the containing panel. Depending on the current size of the window, this may result in some elements that don’t fit, as shown in Figure 4-3.
Figure 4-3. The StackPanel with horizontal orientation Clearly, this doesn’t provide the flexibility real applications need. Fortunately, you can fine-tune the way the StackPanel and other layout containers work using layout properties, as described next.
Layout Properties Although layout is determined by the container, the child elements can still get their say. In fact, layout panels work in concert with their children by respecting a small set of layout properties, as listed in Table 4-3. Table 4-3. Layout Properties
Name
Description
HorizontalAlignment
Determines how a child is positioned inside a layout container when there’s extra horizontal space available. You can choose Center, Left, Right, or Stretch.
VerticalAlignment
Determines how a child is positioned inside a layout container when there’s extra vertical space available. You can choose Center, Top, Bottom, or Stretch.
Margin
Adds a bit of breathing room around an element. The Margin property is an instance of the System.Windows.Thickness structure, with separate components for the top, bottom, left, and right edges.
CHAPTER 4 ■ LAYOUT
Name
Description
MinWidth and MinHeight
Sets the minimum dimensions of an element. If an element is too large for its layout container, it will be cropped to fit.
MaxWidth and MaxHeight Sets the maximum dimensions of an element. If the container has more room available, the element won’t be enlarged beyond these bounds, even if the HorizontalAlignment and VerticalAlignment properties are set to Stretch. Width and Height
Explicitly sets the size of an element. This setting overrides a Stretch value for the HorizontalAlignment or VerticalAlignment properties. However, this size won’t be honored if it’s outside of the bounds set by the MinWidth, MinHeight, MaxWidth, and MaxHeight.
All of these properties are inherited from the base FrameworkElement class and are therefore supported by all the graphical widgets you can use in a WPF window.
■Note As you learned in Chapter 2, different layout containers can provide attached properties to their children. For example, all the children of a Grid object gain Row and Column properties that allow them to choose the cell where they’re placed. Attached properties allow you to set information that’s specific to a particular layout container. However, the layout properties in Table 4-3 are generic enough that they apply to many layout panels. Thus, these properties are defined as part of the base FrameworkElement class.
This list of properties is just as notable for what it doesn’t contain. If you’re looking for familiar position properties, such as Top, Right, and Location, you won’t find them. That’s because most layout containers (all except for the Canvas) use automatic layout and don’t give you the ability to explicitly position elements.
Alignment To understand how these properties work, take another look at the simple StackPanel shown in Figure 4-2. In this example—a StackPanel with vertical orientation—the VerticalAlignment property has no effect because each element is given as much height as it needs and no more. However, the HorizontalAlignment is important. It determines where each element is placed in its row. Ordinarily, the default HorizontalAlignment is Left for a label and Stretch for a Button. That’s why every button takes the full column width. However, you can change these details: A Button Stack Button 1 Button 2 Button 3 Button 4
89
90
CHAPTER 4 ■ LAYOUT
Figure 4-4 shows the result. The first two buttons are given their minimum sizes and aligned accordingly, while the bottom two buttons are stretched over the entire StackPanel. If you resize the window, you’ll see that the label remains in the middle and the first two buttons stay stuck to either side.
Figure 4-4. A StackPanel with aligned buttons
■Note The StackPanel also has its own HorizontalAlignment and VerticalAlignment properties. By default, both of these are set to Stretch, and so the StackPanel fills its container completely. In this example, that means the StackPanel fills the window. If you use different settings, the StackPanel will be made just large enough to fit the widest control.
Margin There’s an obvious problem with the StackPanel example in its current form. A well-designed window doesn’t just contain elements—it also includes a bit of extra space in between the elements. To introduce this extra space and make the StackPanel example less cramped, you can set control margins. When setting margins, you can set a single width for all sides, like this: Button 3 Alternatively, you can set different margins for each side of a control in the order left, top, right, bottom: Button 3 In code, margins are set using the Thickness structure: cmd.Margin = new Thickness(5); Getting the right control margins is a bit of an art because you need to consider how the margin settings of adjacent controls influence one another. For example, if you have two buttons stacked on top of each other, and the topmost button has a bottom margin of 5, and the bottommost button has a top margin of 5, you have a total of 10 units of space between the two buttons.
CHAPTER 4 ■ LAYOUT
Ideally, you’ll be able to keep different margin settings as consistent as possible and avoid setting distinct values for the different margin sides. For instance, in the StackPanel example it makes sense to use the same margins on the buttons and on the panel itself, as shown here: A Button Stack Button 1 Button 2 Button 3 Button 4 This way, the total space between two buttons (the sum of the two button margins) is the same as the total space between the button at the edge of the window (the sum of the button margin and the StackPanel margin). Figure 4-5 shows this more respectable window, and Figure 4-6 shows how the margin settings break down. Window
Button1.Margin.Top StackPanel.Margin.Left
Button1 Button1.Margin.Bottom Button2.Margin.Top Button2 Button2.Margin.Right
StackPanel.Margin.Right
StackPanel.Margin.Bottom
Figure 4-5. Adding margins between elements
Figure 4-6. How margins are combined
Minimum, Maximum, and Explicit Sizes Finally, every element includes Height and Width properties that allow you to give it an explicit size. However, it’s rarely a good idea to take this step. Instead, use the maximum and minimum size properties to lock your control into the right range, if necessary.
■Tip Think twice before setting an explicit size in WPF. In a well-designed layout, it shouldn’t be necessary. If you do add size information, you risk creating a more brittle layout that can’t adapt to changes (such as different languages and window sizes) and truncates your content.
91
92
CHAPTER 4 ■ LAYOUT
For example, you might decide that the buttons in your StackPanel should stretch to fit the StackPanel but be made no larger than 200 units wide and no smaller than 100 units wide. (By default, buttons start with a minimum width of 75 units.) Here’s the markup you need: A Button Stack Button Button Button Button
1 2 3 4
■Tip At this point, you might be wondering if there’s an easier way to set properties that are standardized across several elements, such as the button margins in this example. The answer is styles—a feature that allows you to reuse property settings and even apply them automatically. You’ll learn about styles in Chapter 12.
When the StackPanel sizes a button, it considers several pieces of information: • The minimum size. Each button will always be at least as large as the minimum size. • The maximum size. Each button will always be smaller than the maximum size (unless you’ve incorrectly set the maximum size to be smaller than the minimum size). • The content. If the content inside the button requires a greater width, the StackPanel will attempt to enlarge the button. (You can find out the size that the button wants by examining the DesiredSize property, which returns the minimum width or the content width, whichever is greater.) • The size of the container. If the minimum width is larger than the width of the StackPanel, a portion of the button will be cut off. Otherwise, the button will not be allowed to grow wider than the StackPanel, even if it can’t fit all its text on the button surface. • The horizontal alignment. Because the button uses a HorizontalAlignment of Stretch (the default), the StackPanel will attempt to enlarge the button to fill the full width of the StackPanel. The trick to understanding this process is to realize that the minimum and maximum size set the absolute bounds. Within those bounds, the StackPanel tries to respect the button’s desired size (to fit its content) and its alignment settings. Figure 4-7 sheds some light on how this works with the StackPanel. On the left is the window at its minimum size. The buttons are 100 units each, and the window cannot be resized to be narrower. If you shrink the window from this point, the right side of each button will be clipped off. (You can prevent this possibility by applying the MinWidth property to the window itself, so the window can’t go below a minimum width.) As you enlarge the window, the buttons grow with it until they reach their maximum of 200 units. From this point on, if you make the window any larger the extra space is added to either side of the button (as shown on the right).
CHAPTER 4 ■ LAYOUT
Figure 4-7. Constrained button sizing
■Note In some situations, you might want to use code that checks how large an element is in a window. The Height and Width properties are no help because they indicate your desired size settings, which might not correspond to the actual rendered size. In an ideal scenario, you’ll let your elements size to fit their content, and the Height and Width properties won’t be set at all. However, you can find out the actual size used to render an element by reading the ActualHeight and ActualWidth properties. But remember, these values may change when the window is resized or the content inside it changes.
AUTOMATICALLY SIZED WINDOWS In this example, there’s still one element that has hard-coded sizes: the top-level window that contains the StackPanel (and everything else inside). For a number of reasons, it still makes sense to hard-code window sizes: • In many cases, you want to make a window smaller than the desired size of its child elements. For example, if your window includes a container of scrollable text, you’ll want to constrain the size of that container so that scrolling is possible. You don’t want to make the window ridiculously large so that no scrolling is necessary, which is what the container will request. (You’ll learn more about scrolling in Chapter 5.) • The minimum window size may be usable, but it might not give you the most attractive proportions. Some window dimensions just look better. • Automatic window sizing isn’t constrained by the display size of your monitor. So an automatically sized window might be too large to view. However, automatically sized windows are possible, and they do make sense if you are constructing a simple window with dynamic content. To enable automatic window sizing, remove the Height and Width properties and set the Window.SizeToContent property to WidthAndHeight. The window will make itself just large enough to accommodate all its content. You can also allow a window to resize itself in just one dimension by using a SizeToContent value of Width or Height.
93
94
CHAPTER 4 ■ LAYOUT
The WrapPanel and DockPanel Obviously, the StackPanel alone can’t help you create a realistic user interface. To complete the picture, the StackPanel needs to work with other more capable layout containers. Only then can you assemble a complete window. The most sophisticated layout container is the Grid, which you’ll consider later in this chapter. But first, it’s worth looking at the WrapPanel and DockPanel, which are two more of the simple layout containers provided by WPF. They complement the StackPanel by offering different layout behavior.
The WrapPanel The WrapPanel lays out controls in the available space, one line or column at a time. By default, the WrapPanel.Orientation property is set to Horizontal; controls are arranged from left to right, and then on subsequent rows. However, you can use Vertical to place elements in multiple columns.
■Tip Like the StackPanel, the WrapPanel is really intended for control over small-scale details in a user interface, not complete window layouts. For example, you might use a WrapPanel to keep together the buttons in a toolbarlike control.
Here’s an example that defines a series of buttons with different alignments and places them into the WrapPanel: Top Button Tall Button 2 Bottom Button Stretch Button Centered Button Figure 4-8 shows how the buttons are wrapped to fit the current size of the WrapPanel (which is determined by the size of the window that contains it). As this example demonstrates, a WrapPanel in horizontal mode creates a series of imaginary rows, each of which is given the height of the tallest contained element. Other controls may be stretched to fit or aligned according to the VerticalAlignment property. In the example on the left in Figure 4-8, all the buttons fit into one tall row and are stretched or aligned to fit. In the example on the left, several buttons have been bumped to the second row. Because the second row does not include an unusually tall button, the row height is kept at the minimum button height. As a result, it doesn’t matter what VerticalAlignment setting the various buttons in this row use.
CHAPTER 4 ■ LAYOUT
Figure 4-8. Wrapped buttons
■Note The WrapPanel is the only panel that can’t be duplicated with a crafty use of the Grid.
The DockPanel The DockPanel is a more interesting layout option. It stretches controls against one of its outside edges. The easiest way to visualize this is to think of the toolbars that sit at the top of many Windows applications. These toolbars are docked to the top of the window. As with the StackPanel, docked elements get to choose one aspect of their layout. For example, if you dock a button to the top of a DockPanel, it’s stretched across the entire width of the DockPanel but given whatever height it requires (based on the content and the MinHeight property). On the other hand, if you dock a button to the left side of a container, its height is stretched to fit the container, but its width is free to grow as needed. The obvious question is this: How do child elements choose the side where they want to dock? The answer is through an attached property named Dock, which can be set to Left, Right, Top, or Bottom. Every element that’s placed inside a DockPanel automatically acquires this property. Here’s an example that puts one button on every side of a DockPanel: Top Button Bottom Button Left Button Right Button Remaining Space This example also sets the LastChildFill to true, which tells the DockPanel to give the remaining space to the last element. Figure 4-9 shows the result.
95
96
CHAPTER 4 ■ LAYOUT
Figure 4-9. Docking to every side Clearly, when docking controls, the order is important. In this example, the top and bottom buttons get the full edge of the DockPanel because they’re docked first. When the left and right buttons are docked next, they fit between these two buttons. If you reversed this order, the left and right buttons would get the full sides, and the top and bottom buttons would become narrower because they’d be docked between the two side buttons. You can dock several elements against the same side. In this case, the elements simply stack up against the side in the order they’re declared in your markup. And, if you don’t like the spacing or the stretch behavior, you can tweak the Margin, HorizontalAlignment, and VerticalAlignment properties, just as you did with the StackPanel. Here’s a modified version of the previous example that demonstrates: A Stretched Top Button A Centered Top Button A Left-Aligned Top Button Bottom Button Left Button Right Button Remaining Space The docking behavior is still the same. First the top buttons are docked, then the bottom button, and finally the remaining space is divided between the side buttons and a final button in the middle. Figure 4-10 shows the resulting window.
CHAPTER 4 ■ LAYOUT
Figure 4-10. Docking multiple elements to the top
Nesting Layout Containers The StackPanel, WrapPanel, and DockPanel are rarely used on their own. Instead, they’re used to shape portions of your interface. For example, you could use a DockPanel to place different StackPanel and WrapPanel containers in the appropriate regions of a window. For example, imagine you want to create a standard dialog box with an OK and Cancel button in the bottom right-hand corner, and a large content region in the rest of the window. There are several ways to model this interface with WPF, but the easiest option that uses the panels you’ve seen so far is as follows: 1. Create a horizontal StackPanel to wrap the OK and Cancel buttons together. 2. Place the StackPanel in a DockPanel and use that to dock it to the bottom of the window. 3. Set DockPanel.LastChildFill to true, so you can use the rest of the window to fill in other content. You can add another layout control here, or just an ordinary TextBox control (as in this example). 4. Set the margin properties to give the right amount of whitespace. Here’s the final markup: OK Cancel This is a test.
97
98
CHAPTER 4 ■ LAYOUT
Figure 4-11 shows the rather pedestrian dialog box this creates.
■Note In this example, the Padding adds some minimum space between the button border and the content inside (the word “OK” or “Cancel”). You’ll learn more about Padding when you consider content controls in Chapter 5.
Figure 4-11. A basic dialog box At first glance, this seems like a fair bit more work than placing controls in precise positions using coordinates in a traditional Windows Forms application. And in many cases, it is. However, the longer setup time is compensated by the ease with which you can change the user interface in the future. For example, if you decide you want the OK and Cancel buttons to be centered at the bottom of the window, you simply need to change the alignment of the StackPanel that contains them: This design—a simple window with centered buttons—already demonstrates an end result that wasn’t possible with .NET 1.x (at least not without writing code) and required the specialized layout containers in .NET 2.0. And if you’ve ever looked at the designer code generated by the Windows Forms serialization process, you’ll realize that the markup used here is cleaner, simpler, and more compact. If you add a dash of styles to this window (Chapter 12), you can improve it even further and remove other extraneous details (such as the margin settings) to create a truly adaptable user interface.
The Grid The Grid is the most powerful layout container in WPF. Much of what you can accomplish with the other layout controls is also possible with the Grid. The Grid is also an ideal tool for carving your window into smaller regions that you can manage with other panels. In fact, the Grid
CHAPTER 4 ■ LAYOUT
is so useful that when you add a new XAML document for a window in Visual Studio, it automatically adds the Grid tags as the first-level container, nested inside the root Window element. The Grid separates elements into an invisible grid of rows and columns. Although more than one element can be placed in a single cell (in which case they overlap), it generally makes sense to place just a single element per cell. Of course, that element may itself be another layout container that organizes its own group of contained controls.
■Tip Although the Grid is designed to be invisible, you can set the Grid.ShowGridLines property to true to take a closer look. This feature isn’t really intended for prettying up a window. Instead, it’s a debugging convenience that’s designed to help you understand how the Grid has subdivided itself into smaller regions. This feature is important because you have the ability to control exactly how the Grid chooses column widths and row heights. (Regardless of the ShowGridLines property, gridlines are always shown in the Visual Studio design environment.)
Creating a Grid-based layout is a two-step process. First, you choose the number of columns and rows that you want. Next, you assign the appropriate row and column to each contained element, thereby placing it in just the right spot. You create grids and rows by filling the Grid.ColumnDefinitions and Grid.RowDefinitions collections with objects. For example, if you decide you need two rows and three columns, you’d add the following tags: ... As this example shows, it’s not necessary to supply any information in a RowDefinition or ColumnDefinition element. If you leave them empty (as shown here), the Grid will share the space evenly between all rows and columns. In this example, each cell will be exactly the same size, depending on the size of the containing window. To place individual elements into a cell, you use the attached Row and Column properties. Both these properties take 0-based index numbers. For example, here’s how you could create a partially filled grid of buttons:
99
100
CHAPTER 4 ■ LAYOUT
... Bottom Middle
Each element must be placed into its cell explicitly. This allows you to place more than one element into a cell (which rarely makes sense) or leave certain cells blank (which is often useful). It also means you can declare your elements out of order, as with the final two buttons in this example. However, it makes for clearer markup if you define your controls row by row, and from right to left in each row. There is one exception. If you don’t specify the Grid.Row property, the Grid assumes that it’s 0. The same behavior applies to the Grid.Column property. Thus, you leave both attributes off of an element to place it in the first cell of the Grid.
■Note The Grid fits elements into predefined rows and columns. This is different than layout containers such as the WrapPanel and StackPanel that create implicit rows or columns as they lay out their children. If you want to create a grid that has more than one row and one column, you must define your rows and columns explicitly using RowDefinition and ColumnDefinition objects.
Figure 4-12 shows how this simple grid appears at two different sizes. Notice that the ShowGridLines property is set to true so that you can see the separation between each column and row.
Figure 4-12. A simple grid
CHAPTER 4 ■ LAYOUT
As you would expect, the Grid honors the basic set of layout properties listed in Table 4-3. That means you can add margins around the content in a cell, you can change the sizing mode so an element doesn’t grow to fill the entire cell, and you can align an item along one of the edges of a cell. If you force an element to have a size that’s larger than the cell can accommodate, part of the content will be chopped off.
Fine-Tuning Rows and Columns If the Grid were simply a proportionately sized collection of rows and columns, it wouldn’t be much help. Fortunately, it’s not. To unlock the full potential of the Grid, you can change the way each row and column is sized. The Grid supports three sizing strategies: • Absolute sizes. You choose the exact size using device-independent units. This is the least useful strategy because it’s not flexible enough to deal with changing content size, changing container size, or localization. • Automatic sizes. Each row or column is given exactly the amount of space it needs, and no more. This is one of the most useful sizing modes. • Proportional sizes. Space is divided between a group of rows or columns. This is the standard setting for all rows and columns. For example, in Figure 4-12 you’ll see that all cells increase in size proportionately as the Grid expands. For maximum flexibility, you can mix and match these different sizing modes. For example, it’s often useful to create several automatically sized rows and then let one or two remaining rows get the leftover space through proportional sizing. You set the sizing mode using the Width property of the ColumnDefinition object or the Height property of the RowDefinition object to a number. For example, here’s how you set an absolute width of 100 device-independent units: To use automatic sizing, you use a value of Auto: Finally, to use proportional sizing, you use an asterisk (*): This syntax stems from the world of the Web, where it’s used with HTML frames pages. If you use a mix of proportional sizing and other sizing modes, the proportionally sized rows or columns get whatever space is left over. If you want to divide the remaining space unequally, you can assign a weight, which you must place before the asterisk. For example, if you have two proportionately sized rows and you want the first to be half as high as the second, you could share the remaining space like this:
101
102
CHAPTER 4 ■ LAYOUT
This tells the Grid that the height of the second row should be twice the height of the first row. You can use whatever numbers you like to portion out the extra space.
■Note It’s easy to interact with ColumnDefinition and RowDefinition objects programmatically. You simply need to know that the Width and Height properties are GridLength objects. To create a GridLength that represents a specific size, just pass the appropriate value to the GridLength constructor. To create a GridLength that represents a proportional (*) size, pass the number to the GridLength constructor, and pass GridUnitType.Start as the second constructor argument. To indicate automatic sizing, use the static property GridLength.Auto.
Using these size modes, you can duplicate the simple dialog box example shown in Figure 4-11 using a top-level Grid container to split the window into two rows, rather than a DockPanel. Here’s the markup you’d need: This is a test. OK Cancel
■Tip This Grid doesn’t declare any columns. This is a shortcut you can take if your grid uses just one column and that column is proportionately sized (so it fills the entire width of the Grid).
This markup is slightly longer, but it has the advantage of declaring the controls in the order they appear, which makes it easier to understand. In this case, the approach you take is simply a matter of preference. And if you want, you could replace the nested StackPanel with a one-row, two-column Grid.
■Note You can create almost any interface using nested Grid containers. (One exception is wrapped rows or columns that use the WrapPanel.) However, when you’re dealing with small sections of user interface or laying out a small number of elements, it’s often simpler to use the more specialized StackPanel and DockPanel containers.
CHAPTER 4 ■ LAYOUT
Spanning Rows and Columns You’ve already seen how you place elements in cells using the Row and Column attached properties. You can also use two more attached properties to make an element stretch over several cells: RowSpan and ColumnSpan. These properties take the number of rows or columns that the element should occupy. For example, this button will take all the space that’s available in the first and second cell of the first row: Span Button And this button will stretch over four cells in total by spanning two columns and two rows: Span Button Row and column spanning can achieve some interesting effects and is particularly handy when you need to fit elements in a tabular structure that’s broken up by dividers or longer sections of content. Using column spanning, you could rewrite the simple dialog box example from Figure 4-11 using just a single Grid. This Grid divides the window into three columns, spreads the text box over all three, and uses the last two columns to align the OK and Cancel buttons. This is a test. OK Cancel Most developers will agree that this layout isn’t clear or sensible. The column widths are determined by the size of the two buttons at the bottom of the window, which makes it difficult to add new content into the existing Grid structure. If you make even a minor addition to this window, you’ll probably be forced to create a new set of columns. As this shows, when you choose the layout containers for a window, you aren’t simply interested in getting the correct layout behavior—you also want to build a layout structure that’s easy to maintain and enhance in the future. A good rule of thumb is to use smaller layout containers such as the StackPanel for one-off layout tasks, such as arranging a group of
103
104
CHAPTER 4 ■ LAYOUT
buttons. On the other hand, if you need to apply a consistent structure to more than one area of your window (as with the text box column shown later in Figure 4-20), the Grid is an indispensable tool for standardizing your layout.
Split Windows Every Windows user has seen splitter bars—draggable dividers that separate one section of a window from another. For example, when you use Windows Explorer, you’re presented with a list of folders (on the left) and a list of files (on the right). You can drag the splitter bar in between to determine what proportion of the window is given to each pane. In WPF, splitter bars are represented by the GridSplitter class and are a feature of the Grid. By adding a GridSplitter to a Grid, you give the user the ability to resize rows or columns. Figure 4-13 shows a window where a GridSplitter sits between two columns. By dragging the splitter bar, the user can change the relative widths of both columns.
Figure 4-13. Moving a splitter bar Most programmers find that the GridSplitter isn’t the most intuitive part of WPF. Understanding how to use it to get the effect you want takes a little experimentation. Here are a few guidelines: • The GridSplitter must be placed in a Grid cell. You can place the GridSplitter in a cell with existing content, in which case you need to adjust the margin settings so it doesn’t overlap. A better approach is to reserve a dedicated column or row for the GridSplitter, with a Height or Width value of Auto. • The GridSplitter always resizes entire rows or columns (not single cells). To make the appearance of the GridSplitter consistent with this behavior, you should stretch the GridSplitter across an entire row or column, rather than limit it to a single cell. To accomplish this, you use the RowSpan or ColumnSpan properties you considered earlier. For example, the GridSplitter in Figure 4-13 has a RowSpan of 2. As a result, it stretches over the entire column. If you didn’t add this setting, it would only appear in the top row (where it’s placed), even though dragging the splitter bar would resize the entire column.
CHAPTER 4 ■ LAYOUT
• Initially, the GridSplitter is invisibly small. To make it usable, you need to give it a minimum size. In the case of a vertical splitter bar (like the one in Figure 4-13), you need to set the VerticalAlignment to Stretch (so it fills the whole height of the available area) and the Width to a fixed size (such as 10 device-independent units). In the case of a horizontal splitter bar, you need to set HorizontalAlignment to Stretch, and Height to a fixed size. • The GridSplitter alignment also determines whether the splitter bar is horizontal (used to resize rows) or vertical (used to resize columns). In the case of a horizontal splitter bar, you should set VerticalAligment to Center (which is the default value) to indicate that dragging the splitter resizes the rows that are above and below. In the case of a vertical splitter bar (like the one in Figure 4-13), you should set HorizontalAlignment to Center to resize the columns on either side.
■Note You can change the resizing behavior using the ResizeDirection and ResizeBehavior properties of the GridSplitter. However, it’s simpler to let this behavior depend entirely on the alignment settings, which is the default.
Dizzy yet? To reinforce these rules, it helps to take a look at the actual markup for the example shown in Figure 4-13. In the following listing, the GridSplitter details are highlighted: Right
105
106
CHAPTER 4 ■ LAYOUT
■Tip To create a successful GridSplitter, make sure you supply values for the VerticalAlignment, HorizontalAlignment, and Width (or Height) properties.
This markup includes one additional detail. When the GridSplitter is declared, the ShowsPreview property is set to false. As a result, when the splitter bar is dragged from one side to another, the columns are resized immediately. But if you set ShowsPreview to true, when you drag you’ll see a gray shadow follow your mouse pointer to show you where the split will be. The columns won’t be resized until you release the mouse button. It’s also possible to use the arrow keys to resize a GridSplitter once it receives focus. The ShowsPreview isn’t the only GridSplitter property that you can set. You can also adjust the DragIncrement property if you want to force the splitter to move in coarser “chunks” (such as 10 units at a time). If you want to control the maximum and minimum allowed sizes of the columns, you simply make sure the appropriate properties are set in the ColumnDefinitions section, as shown in the previous example.
■Tip You can change the fill that’s used for the GridSplitter so that it isn’t just a shaded gray rectangle. The trick is to use the Background property, which accepts simple colors and more complex brushes. You’ll learn more in Chapter 7.
A Grid usually contains no more than a single GridSplitter. However, you can nest one Grid inside another, and if you do, each Grid may have its own GridSplitter. This allows you to create a window that’s split into two regions (for example, a left and right pane), and then further subdivide one of these regions (say, the pane on the right) into more sections (such as a resizable top and bottom portion). Figure 4-14 shows an example.
Figure 4-14. Resizing a window with two splits
CHAPTER 4 ■ LAYOUT
Creating this window is fairly straightforward, although it’s a chore to keep track of the three Grid containers that are involved: the overall Grid, the nested Grid on the left, and the nested Grid on the right. The only trick is to make sure the GridSplitter is placed in the correct cell and given the correct alignment. Here’s the complete markup: Top Left Bottom Left Top Right Bottom Right
107
108
CHAPTER 4 ■ LAYOUT
■Tip Remember, if a Grid has just a single row or column, you can leave out the RowDefinitions section. Also, elements that don’t have their row position explicitly set are assumed to have a Grid.Row value of 0 and are placed in the first row. The same holds true for elements that don’t supply a Grid.Column value.
Shared Size Groups As you’ve seen, a Grid contains a collection of rows and columns, which are sized explicitly, proportionately, or based on the size of their children. There’s one other way to size a row or a column—to match the size of another row or column. This works through a feature called shared size groups. The goal of shared size groups is to keep separate portions of your user interface consistent. For example, you might want to size one column to fit its content and size another column to match that size exactly. However, the real benefit of shared size groups is to give the same proportions to separate Grid controls. To understand how this works, consider the example shown in Figure 4-15. This window features two Grid objects—one at the top of the window (with three columns) and one at the bottom (with two columns). The leftmost column of the first Grid is sized proportionately to fit its content (a long text string). The leftmost column of the second Grid has exactly the same width, even though it contains less content. That’s because it shares the same size group. No matter how much content you stuff in the first column of the first Grid, the first column of the second Grid stays synchronized. As this example demonstrates, a shared column can be used in otherwise different grids. In this example, the top Grid has an extra column, and so the remaining space is divided differently. Similarly, the shared columns can occupy different positions, so you could create a relationship between the first column in one Grid and the second column in another. And obviously, the columns can host completely different content.
Figure 4-15. Two grids that share a column definition
CHAPTER 4 ■ LAYOUT
When you use a shared size group, it’s as if you’ve created one column (or row) definition, which is reused in more than one place. It’s not a simple one-way copy of one column to another. You can test this out with the previous example by changing the content in the shared column of the second Grid. Now, the column in the first Grid will be lengthened to match (Figure 4-16). You can even add a GridSplitter to one of the Grid objects. As the user resizes the column in one Grid, the shared column in the other Grid will follow along, resizing itself at the same time.
Figure 4-16. Shared-size columns remain synchronized Creating a shared group is easy. You simply need to set the SharedSizeGroup property on both columns, using a matching string. In the current example, both columns use a group named TextLabel: A very long bit of text More text A text box ...
109
110
CHAPTER 4 ■ LAYOUT
Short A text box There’s one other detail. Shared size groups aren’t global to your entire application because more than one window might inadvertently use the same name. You might assume that shared size groups are limited to the current window, but WPF is even more stringent than that. To share a group, you need to explicitly set the attached Grid.IsSharedSizeScope property to true on a container somewhere upstream that holds the Grid objects with the shared column. In the current example, the top and bottom Grid are wrapped in another Grid that accomplishes this purpose, although you could just as easily use a different container such as a DockPanel or StackPanel. Here’s the markup for the top-level Grid: ... Some text in between the two grids... ...
■Tip You could use a shared size group to synchronize a separate Grid with column headers. The width of each column can then be determined by the content in the column, which the header will share. You could even place a GridSplitter in the header, which the user could drag to resize the header and the entire column underneath.
The UniformGrid There is a grid that breaks all the rules you’ve learned about so far: the UniformGrid. Unlike the Grid, the UniformGrid doesn’t require (or even support) predefined columns and rows. Instead, you simply set the Rows and Columns properties to set its size. Each cell is always the same size because the available space is divided equally. Finally, elements are placed into the appropriate cell based on the order in which you define them. There are no attached Row and Column properties, and no blank cells. Here’s an example that fills a UniformGrid with four buttons: Top Left
CHAPTER 4 ■ LAYOUT
Top Right Bottom Left Bottom Right The UniformGrid is used far less frequently than the Grid. The Grid is an all-purpose tool for creating window layouts from the simple to the complex. The UniformGrid is a much more specialized layout container that’s primarily useful when quickly laying out elements in a rigid grid (for example, when building a playing board for certain games). Many WPF programmers will never use the UniformGrid.
Coordinate-Based Layout with the Canvas The only layout container you haven’t considered yet is the Canvas. It allows you to place elements using exact coordinates, which is a poor choice for designing rich data-driven forms and standard dialogs, but a valuable tool if you need to build something a little different (such as a drawing surface for a diagramming tool). The Canvas is also the most lightweight of the layout containers. That’s because it doesn’t include any complex layout logic to negotiate the sizing preferences of its children. Instead, it simply lays them all out at the position they specify, with the exact size they want. To position an element on the Canvas, you set the attached Canvas.Left and Canvas.Top properties. Canvas.Left sets the number of units between the left edge of your element and the left edge of the Canvas. Canvas.Top sets the number of units between the top of your element and the top of the Canvas. As always, these values are set in device-independent units, which line up with ordinary pixels exactly when the system DPI is set to 96 dpi.
■Note Alternatively, you can use Canvas.Right instead of Canvas.Left to space an element from the right edge of the Canvas, and Canvas.Bottom instead of Canvas.Top to space it from the bottom. You just can’t use both Canvas.Right and Canvas.Left at once, or both Canvas.Top and Canvas.Bottom.
Optionally, you can size your element explicitly using its Width and Height properties. This is more common when using the Canvas than it is in other panels because the Canvas has no layout logic of its own. (And often, you’ll use the Canvas when you need precise control over how a combination of elements is arranged.) If you don’t set the Width and Height properties, your element will get its desired size—in other words, it will grow just large enough to fit its content. Here’s a simple Canvas that includes four buttons: (10,10) (120,30) (60,80) (70,120)
111
112
CHAPTER 4 ■ LAYOUT
Figure 4-17 shows the result.
Figure 4-17. Explicitly positioned buttons in a Canvas If you resize the window, the Canvas stretches to fill the available space, but none of the controls in the Canvas move or change size. The Canvas doesn’t include any of the anchoring or docking features that were provided with coordinate layout in Windows Forms. Part of the reason for this gap is to keep the Canvas lightweight. Another reason is to prevent people from using the Canvas for purposes for which it’s not intended (such as laying out a standard user interface). Like any other layout container, the Canvas can be nested inside a user interface. That means you can use the Canvas to draw some detailed content in a portion of your window, while using more standard WPF panels for the rest of your elements.
■Tip If you use the Canvas alongside other elements, you may want to consider setting its ClipToBounds to true. That way, elements inside the Canvas that stretch beyond its bounds are clipped off at the edge of the Canvas. (This prevents them from overlapping other elements elsewhere in your window.) All the other layout containers always clip their children to fit, regardless of the ClipToBounds setting.
Z-Order If you have more than one overlapping element, you can set the attached Canvas.ZIndex property to control how they are layered. Ordinarily, all the elements you add have the same ZIndex—0. When elements have the same ZIndex, they’re displayed in the same order that they exist in Canvas.Children collection, which is based on the order that they’re defined in the XAML markup. Elements declared later in the markup—such as button (70,120)—are displayed overtop of elements that are declared earlier—such as button (120,30). However, you can promote any element to a higher level by increasing its ZIndex. That’s because higher ZIndex elements always appear over lower ZIndex elements. Using this technique, you could reverse the layering in the previous example:
CHAPTER 4 ■ LAYOUT
(60,80) (70,120)
■Note The actual values you use for the Canvas.ZIndex property have no meaning. The important detail is how the ZIndex value of one element compares to the ZIndex value of another. You can set the ZIndex using any positive or negative integer.
The ZIndex property is particularly useful if you need to change the position of an element programmatically. Just call Canvas.SetZIndex() and pass in the element you want to modify and the new ZIndex you want to apply. Unfortunately, there is no BringToFront() or SendToBack() method—it’s up to you to keep track of the highest and lowest ZIndex values if you want to implement this behavior.
The InkCanvas WPF also includes an InkCanvas element that’s similar to the Canvas in some respects (and wholly different in others). Like the Canvas, the InkCanvas defines four attached properties that you can apply to child elements for coordinate-based positioning (Top, Left, Bottom, and Right). However, the underlying plumbing is quite a bit different—in fact, the InkCanvas doesn’t derive from Canvas, or even from the base Panel class. Instead, it derives directly from FrameworkElement. The primary purpose of the InkCanvas is to allow stylus input. The stylus is the penlike input device that’s used in tablet PCs. However, the InkCanvas works with the mouse in the same way as it works with the stylus. Thus, a user can draw lines or select and manipulate elements in the InkCanvas using the mouse. The InkCanvas actually holds two collections of child content. The familiar Children collection holds arbitrary elements, just as with the Canvas. Each element can be positioned based on the Top, Left, Bottom, and Right properties. The Strokes collection holds System.Windows.Ink.Stroke objects, which represent graphical input that the user has drawn in the InkCanvas. Each line or curve that the user draws becomes a separate Stroke object. Thanks to these dual collections, you can use the InkCanvas to let the user annotate content (stored in the Children collection) with strokes (stored in the Strokes collection). For example, Figure 4-18 shows an InkCanvas that contains a picture that has been annotated with extra strokes. Here’s the markup for the InkCanvas in this example, which defines the image:
113
114
CHAPTER 4 ■ LAYOUT
The strokes are drawn at runtime by the user.
Figure 4-18. Adding strokes in an InkCanvas The InkCanvas can be used in some significantly different ways, depending on the value you set for the InkCanvas.EditingMode property. Table 4-4 lists all your options. Table 4-4. Values of the InkCanvasEditingMode Enumeration
Name
Description
Ink
The InkCanvas allows the user to draw annotations. This is the default mode. When the user draws with the mouse or stylus, a stroke is drawn.
GestureOnly
The InkCanvas doesn’t allow the user to draw stroke annotations but pays attention to specific predefined gestures (such as dragging the stylus in one direction, or scratching out content). The full list of recognized gestures is listed by the System.Windows.Ink.ApplicationGesture enumeration.
InkAndGesture
The InkCanvas allows the user to draw stroke annotations and also recognizes predefined gestures.
EraseByStroke
The InkCanvas erases a stroke when it’s clicked. If the user has a stylus, he can switch to this mode by using the back end of the stylus. (You can determine the current mode using the read-only ActiveEditingMode property, and you can change the mode used for the back end of the stylus by changing the EditingModeInverted property.)
EraseByPoint
The InkCanvas erases a portion of a stroke (a point in a stroke) when that portion is clicked.
Select
The InkCanvas allows the user to select elements that are stored in the Children collection. To select an element, the user must click it or drag a selection “lasso” around it. Once an element is selected, it can be moved, resized, or deleted.
None
The InkCanvas ignores mouse and stylus input.
CHAPTER 4 ■ LAYOUT
The InkCanvas raises events when the editing mode changes (ActiveEditingModeChanged), a gesture is detected in GestureOnly or InkAndGesture mode (Gesture), a stroke is drawn (StrokeCollected), a stroke is erased (StrokeErasing and StrokeErased), and an element is selected or changed in Select mode (SelectionChanging, SelectionChanged, SelectionMoving, SelectionMoved, SelectionResizing, and SelectionResized). The events that end in ing represent an action that is about to take place but can be canceled by setting the Cancel property of the EventArgs object. In Select mode, the InkCanvas provides a fairly capable design surface for dragging content around and manipulating it. Figure 4-19 shows a Button control in an InkCanvas as it’s being selected (on the left) and then repositioned and resized (on the right).
Figure 4-19. Moving and resizing an element in the InkCanvas As interesting as Select mode is, it isn’t a perfect fit if you’re building a drawing or diagramming tool. You’ll see a better example of how to create a custom drawing surface in Chapter 14.
Layout Examples You’ve now spent a considerable amount of time poring over the intricacies of the WPF layout containers. With this low-level knowledge in mind, it’s worth looking at a few complete layout examples. Doing so will give you a better sense of how the various WPF layout concepts (such as size-to-content, stretch, and nesting) work in real-world windows.
A Column of Settings Layout containers such as the Grid make it dramatically easier to create an overall structure to a window. For example, consider the window with settings shown in Figure 4-20. This window arranges its individual components—labels, text boxes, and buttons—into a tabular structure.
115
116
CHAPTER 4 ■ LAYOUT
Figure 4-20. Folder settings in a column To create this table, you begin by defining the rows and columns of the grid. The rows are easy enough—each one is simply sized to the height of the containing content. That means the entire row will get the height of the largest element, which in this case is the Browse button in the third column. ... Next, you need to create the columns. The first and last columns are sized to fit their content (the label text and the Browse button, respectively). The middle column gets all the remaining room, which means it grows as the window is resized larger, giving you more room to see the selected folder. (If you want this stretching to top out at some extremely wide maximum value, you can use the MaxWidth property when defining the column, just as you do with individual elements.) ... ...
CHAPTER 4 ■ LAYOUT
■Tip The Grid needs some minimum space—enough to fit the full label text, the browse button, and a few pixels in the middle column to show the text box. If you shrink the containing window to be smaller than this, some content will be cut off. As always, it makes sense to use the MinWidth and MinHeight properties on the window to prevent this from occurring.
Now that you have your basic structure, you simply need to slot the elements into the right cells. However, you also need to think carefully about margins and alignment. Each element needs a basic margin (a good value is 3 units) to give some breathing room. In addition, the label and text box need to be centered vertically because they aren’t as tall as the Browse button. Finally, the text box needs to use automatic sizing mode, so it stretches to fit the entire column. Here’s the markup you need to define the first row in the grid: ... Home: Browse ... You can repeat this markup to add all your rows by simply incrementing the value of the Grid.Row attribute. One fact that’s not immediately obvious is how flexible this window is because of the use of the Grid control. None of the individual elements—the labels, text boxes, and buttons— have hard-coded positions or sizes. As a result, you can quickly make changes to the entire grid simply by tweaking the ColumnDefinition elements. Furthermore, if you add a row that has longer label text (necessitating a wider first column), the entire grid is adjusted to be consistent, including the rows that you’ve already added. And if you want to add elements in between the rows—such as separator lines to divide different sections of the window—you can keep the same columns but use the ColumnSpan property to stretch a single element over a larger area.
Dynamic Content As the column of settings demonstrates, windows that use the WPF layout containers are easy to change and adapt as you revise your application. This flexibility doesn’t just benefit you at design time. It’s also a great asset if you need to display content that changes dramatically. One example is localized text—text that appears in your user interface and needs to be translated into different languages for different geographic regions. In old-style coordinatebased applications, changing the text can wreak havoc in a window, particularly because a short amount of English text becomes significantly larger in many languages. Even if elements are allowed to resize themselves to fit larger text, doing so often throws off the whole balance of a window.
117
118
CHAPTER 4 ■ LAYOUT
Figure 4-21 demonstrates how this isn’t the case when you use the WPF layout containers intelligently. In this example, the user interface has a short text and a long text option. When the long text is used, the buttons that contain the text are resized automatically and other content is bumped out of the way. And because the resized buttons share the same layout container (in this case, a table column), that entire section of the user interface is resized. The end result is that all buttons keep a consistent size—the size of the largest button.
Figure 4-21. A self-adjusting window To make this work, the window is carved into a table with two columns and two rows. The column on the left takes the resizable buttons, while the column on the right takes the text box. The bottom row is used for the Close button. It’s kept in the same table so that it resizes along with the top row. Here’s the complete markup: Prev Next Show Long Text
CHAPTER 4 ■ LAYOUT
This is a test that demonstrates how buttons adapt themselves to fit the content they contain when they aren't explicitly sized. This behavior makes localization much easier. Close
A Modular User Interface Many of the layout containers gracefully “flow” content into the available space, like the StackPanel, DockPanel, and WrapPanel. One advantage of this approach is that it allows you to create truly modular interfaces. In other words, you can plug in different panels with the appropriate user interface sections you want to show and leave out those that don’t apply. The entire application can shape itself accordingly, somewhat like a portal site on the Web. Figure 4-22 demonstrates. It places several separate panels into a WrapPanel. The user can choose which of these panels are visible using the check boxes at the top of the window.
Figure 4-22. A series of panels in a WrapPanel
■Note Although you can set the background of a layout panel, you can’t set a border around it. This example overcomes that limitation by wrapping each panel in a Border element that outlines the exact dimensions. You’ll learn how to use the Border and other similarly specialized containers in the next chapter.
119
120
CHAPTER 4 ■ LAYOUT
As different panels are hidden, the remaining panels reflow themselves to fit the available space (and the order in which they’re declared). Figure 4-23 shows a different permutation of panels.
Figure 4-23. Hiding some panels To hide and show the individual panels, a small bit of code handles check box clicks. Although you haven’t considered the WPF event handling model in any detail (Chapter 6 has the full story), the trick is to set the Visibility property: panel.Visibility = Visibility.Collapsed; The Visibility property is a part of the base UIElement class and is therefore supported by just about everything you’ll put in a WPF window. It takes one of three values, from the System.Windows.Visibility enumeration, as listed in Table 4-5. Table 4-5. Values of the Visibilty Enumeration
Value
Description
Visible
The element appears as normal in the window.
Collapsed
The element is not displayed and doesn’t take up any space.
Hidden
The element is not displayed, but the space it would otherwise use is still reserved. (In other words, there’s a blank space where it would have appeared). This setting is handy if you need to hide and show elements without changing the layout and the relative positioning of the elements in the rest of your window.
CHAPTER 4 ■ LAYOUT
■Tip You can use the Visibility property to dynamically tailor a variety of interfaces. For example, you could make a collapsible pane that can appear at the side of your window. All you need to do is wrap all the contents of that pane in some sort of layout container and set its Visibility property to suit. The remaining content will be rearranged to fit the available space.
The Last Word In this chapter, you took a detailed tour of the new WPF layout model and learned how to place elements in stacks, grids, and other arrangements. You built more complex layouts using nested combinations of the layout containers, and you threw the GridSplitter into the mix to make resizable split windows. And all along, you kept close focus on the reasons for this dramatic change—namely, the benefits you’ll get when maintaining, enhancing, and localizing your user interface. The layout story is still far from over. In the following chapters, you’ll see many more examples that use the layout containers to organize groups of elements. You’ll also learn about a few additional features that let you arrange content in a window: • Specialized containers. The Border, ScrollViewer, and Expander give you the ability to create content that has borders, can be scrolled, and can be collapsed out of sight. Unlike the layout panels, these containers can only hold a single piece of content. However, you can easily use them in concert with a layout panel to get exactly the effect you need. You’ll try out these containers in Chapter 5. • The Viewbox. Need a way to resize graphical content (such as images and vector drawings)? The Viewbox is yet another specialized container that can help you out, and it has built in scaling. You’ll take your first look at the Viewbox in Chapter 5. • Text layout. WPF adds new tools for laying out large blocks of styled text. You can use floating figures and lists, and use paging, columns, and sophisticated wrapping intelligence to get remarkably polished results. You’ll see how in Chapter 19.
121
CHAPTER
5
■■■
Content I
n the previous chapter you explored the WPF layout system, which lets you arrange a window by placing elements into specialized layout containers. With this system, even a simple window breaks down to a nested series of Grid, StackPanel, and DockPanel containers. Dig deep enough and you’ll eventually find the visible elements (widgets such as buttons, labels, and text boxes) inside the various containers. However, the layout containers aren’t the only example of nested elements. In fact, WPF is designed with a new content model that lets you place elements inside other elements that are otherwise ordinary. Using this technique, you can take many simple controls—such as buttons—and place pictures, vector shapes, and even layout containers inside. This content model is one of the details that make WPF so remarkably flexible. In this chapter, you’ll explore the base ContentControl class that supports this model. You’ll also learn how to use more specialized ContentControl descendants to make your panels scrollable and collapsible.
Understanding Content Controls In Chapter 1, you took a look at the class hierarchy that’s at the core of WPF. You also considered the difference between elements (which include everything you’ll place in a WPF window) and controls (which are more specialized elements that derive from the System.Windows. Controls.Control class). In the world of WPF, a control is generally described as an element that can receive focus and accept user input, such as a text box or a button. However, the distinction is sometimes a bit blurry. The ToolTip is considered to be a control because it appears and disappears depending on the user’s mouse movements. The Label is considered to be a control because of its support for mnemonics (shortcut keys that transfer the focus to related controls). Content controls are a still more specialized type of controls that are able to hold (and display) a piece of content. Technically, a content control is a control that can contain a single nested element. The one-child limit is what differentiates content controls from layout containers, which can hold as many nested elements as you want.
123
124
CHAPTER 5 ■ CONTENT
■Tip Of course, you can still pack in a lot of content in a single content control—the trick is to wrap everything in a single container, such as a StackPanel or a Grid. For example, the Window class is itself a content control. Obviously, windows often hold a great deal of content, but it’s all wrapped in one top-level container. (Typically, this container is a Grid.)
As you learned last chapter, all WPF layout containers derive from the abstract Panel class, which gives the support for holding multiple elements. Similarly, all content controls derive from the abstract ContentControl class. Figure 5-1 shows the class hierarchy.
DispatcherObject
Legend Abstract Class
DependencyObject Concrete Class Visual
UIElement
FrameworkElement
Control
ContentControl
Label
ScrollViewer
ButtonBase
UserControl
ToolTip
Window
HeaderedContentControl
GroupBox
TabItem
Expander
Figure 5-1. The hierarchy of content controls
CHAPTER 5 ■ CONTENT
As Figure 5-1 shows, several common controls are actually content controls, including the Label and the ToolTip. Additionally, all types of buttons are content controls, including the familiar Button, the RadioButton, and the CheckBox. There are also a few more specialized content controls, such as ScrollViewer (which allows you to create a scrollable panel), and UserControl class (which allows you to reuse a custom grouping of controls). The Window class, which is used to represent each window in your application, is itself a content control. Finally, there is a subset of content controls that goes through one more level of inheritance by deriving from the HeaderedContentControl class. These controls have both a content region and a header region, which can be used to display some sort of title. These controls include GroupBox, TabItem (a page in a TabControl), and Expander.
■Note Figure 5-1 leaves out very little. It doesn’t show the Frame element that’s used for content navigation (Chapter 9), and it omits a few elements that are used inside other controls (such as list box and status bar items).
The Content Property Whereas the Panel class adds the Children collection to hold nested elements, the ContentControl class adds a Content property, which accepts a single object. The Content property supports any type of object, but it separates objects into two groups and gives each group different treatment: • Objects that don’t derive from UIElement. The content control class calls ToString() to get the text for these controls and then displays that text. • Objects that derive from UIElement. These objects (which include all the visual elements that are a part of WPF) are displayed inside the content control using the UIElement.OnRender() method.
■Note Technically, the OnRender() method doesn’t draw the object immediately—it simply generates a graphical representation that WPF paints on the screen as needed.
To understand how this works, consider the humble button. So far, the examples that you’ve seen that include buttons have simply supplied a string: Text content This string is set as the button content and displayed on the button surface. However, you can get more ambitious by placing other elements inside the button. For example, you can place an image inside using the Image class:
125
126
CHAPTER 5 ■ CONTENT
Or you could combine text and images by wrapping them all in a layout container like the StackPanel: Image and text button Courtesy of the StackPanel You’ll notice that this example uses the TextBlock instead of a Label control (although either one would work). The TextBlock is a lightweight text element that supports wrapping but doesn’t support shortcut keys. Unlike the Label, the TextBlock is not a content control. Chapter 7 describes both the TextBlock and Label in more detail.
■Note It’s acceptable to place text content inside a content control because the XAML parser converts that to a string object and uses that to set the Content property. However, you can’t place string content directly in a layout container. Instead, you need to wrap it in a class that derives from UIElement, such as TextBlock or Label.
If you want to create a truly exotic button, you could even place other content controls such as text boxes and buttons inside (and nest still elements inside these). It’s doubtful that such an interface would make much sense, but it is possible. Figure 5-2 shows some sample buttons.
Figure 5-2. Buttons with different types of nested content
CHAPTER 5 ■ CONTENT
This is the exact same content model you saw with windows. Just like the Button class, the Window class allows a single nested element, which can be a piece of text, an arbitrary object, or an element.
■Note One of the few elements that is not allowed inside a content control is the Window. When you create a Window, it checks to see if it’s the top-level container. If it’s placed inside another element, the Window throws an exception.
Aside from the Content property, the ContentControl class adds very little. It includes a HasContent property that returns true if there is content in the control, and a ContentTemplate that allows you to build a template telling the control how to display an otherwise unrecognized object. Using ContentTemplate, you can display non-UIElement-derived objects more intelligently. Instead of just calling ToString() to get a string, you can take various property values and arrange them into more complex markup. You’ll learn more about WPF data binding in Chapter 16, and data templates in Chapter 17.
Aligning Content In Chapter 4, you learned how to align different controls in a container using the HorizontalAlignment and VerticalAlignment properties, which are defined in the base FrameworkElement class. However, once a control contains content there’s another level of organization to think about. You need to decide how the content inside your content control is aligned with its borders. This is accomplished using the HorizontalContentAlignment and VerticalContentAlignment properties. HorizontalContentAlignment and VerticalContentAlignment support the same values as HorizontalAlignment and VerticalAlignment. That means you can line content up on the inside of any edge (Top, Bottom, Left, or Right), you can center it (Center), or you can stretch it to fill the available space (Stretch). These settings are applied directly to the nested content element, but you can use multiple levels of nesting to create a sophisticated layout. For example, if you nest a StackPanel in a Label element, the Label.HorizontalContentAlignment determines where the StackPanel is placed, but the alignment and sizing options of the StackPanel and its children will determine the rest of the layout. In Chapter 4, you also learned about the Margin property, which allows you to add whitespace between adjacent elements. Content controls use a complementary property named Padding, which inserts space between the edges of the control and the edges of the content. To see the difference compare the following two buttons: Absolutely No Padding Well Padded The button that has no padding (the default) has its text crowded up against the button edge. The button that has a padding of 3 units on each side gets a more respectable amount of breathing space. Figure 5-3 highlights the difference.
127
128
CHAPTER 5 ■ CONTENT
Figure 5-3. Padding the content of button
■Note The HorizontalContentAlignment, VerticalContentAlignment, and Padding properties are all defined as part of the Control class, not the more specific ContentControl class. That’s because there may be controls that aren’t content controls but still have some sort of content. One example is the TextBox—its contained text (stored in the Text property) is adjusted using the alignment and padding settings you’ve applied.
The WPF Content Philosophy At this point, you might be wondering if the WPF content model is really worth all the trouble. After all, you might choose to place an image inside a button but you’re unlikely to embed other controls and entire layout panels. However, there are a few important reasons driving the shift in perspective. Consider the example shown in Figure 5-2, which includes a simple image button that places an Image element inside the Button control. This approach is less than ideal, because bitmaps are not resolution independent. On a high-dpi display, the bitmap may appear blurry because WPF must add more pixels by interpolation to make sure the image stays the correct size. More sophisticated WPF interfaces avoid bitmaps and use a combination of vector shapes to create custom-drawn buttons and other graphical frills (as you’ll see in Chapter 13). This approach integrates nicely with the content control model. Because the Button class is a content control, you aren’t limited to filling it with a fixed bitmap—instead, you can include other content. For example, you can use the classes in the System.Windows.Shapes namespace to draw a vector image inside a button. Here’s an example that creates a button with two diamond shapes (as shown in Figure 5-4):
CHAPTER 5 ■ CONTENT
Figure 5-4. A button with shape content Clearly, in this case the nested content model is simpler than adding extra properties to the Button class to support the different types of content. Not only is the nested content model more flexible, it also allows the Button class to expose a simpler interface. And because all content controls support content nesting in the same way, there’s no need to add different content properties to multiple classes. (Version 2.0 of the .NET Framework ran into this issue while enhancing the Button and Label class to better support images and mixed image-andtext content.) In essence, the nested content model is a trade. It simplifies the class model for elements because there’s no need to use additional layers of inheritance to add properties for different types of content. However, you need to use a slightly more complex object model—elements that can be built out of other nested elements.
■Note You can’t always get the effect you want by changing the content of a control. For example, even though you can place any content in a button, a few details never change, such as the button’s shaded background, its rounded border, and the mouse-over effect that makes it glow when you move the mouse pointer over it. However, there’s another way to change these built-in details—by applying a new control template. Chapter 15 shows how you can change all aspects of a control’s look and feel using a control template.
Specialized Containers In Chapter 7, you’ll consider all the control basics and look at simple content controls such as the Label and Button in more detail. But first, it’s worth taking a detour to consider a few more sophisticated content controls: ScrollViewer, GroupBox, TabItem, and Expander. All of these controls are designed to help you shape large portions of your user interface. However, because these controls can only hold a single element, you’ll usually use them in conjunction with a layout container.
The ScrollViewer In the previous chapter, you tried out several containers. However, none of them provided support for scrolling, which is a key feature if you want to fit large amounts of content in a limited amount of space. In WPF, scrolling support is easy to get, but it requires another ingredient: the ScrollViewer content control.
129
130
CHAPTER 5 ■ CONTENT
In order to get scrolling support, you need to wrap the content you want to scroll inside a ScrollViewer. Although the ScrollViewer can hold anything, you’ll typically use it to wrap a layout container. For example, in Chapter 4 you saw an example that used a Grid element to create a three-column display of texts, text boxes, and buttons. To make this Grid scrollable, you simply need to wrap the Grid in a ScrollViewer, as shown in this slightly shortened markup: ... ... Home: Browse ... The result is shown in Figure 5-5.
Figure 5-5. A scrollable window
CHAPTER 5 ■ CONTENT
If you resize the window in this example so that it’s large enough to fit all its content, the scroll bar becomes disabled. However, the scroll bar will still be visible. You can control this behavior by setting the VerticalScrollBarVisibility property, which takes a value from the ScrollBarVisibility enumeration. The default value of Visible makes sure the vertical scroll bar is always present. Use Auto if you want the scroll bar to appear when it’s needed and disappear when it’s not. Or use Disabled if you don’t want the scroll bar to appear at all.
■Note You can also use Hidden, which is similar to Disabled but subtly different. First, content with a hidden scroll bar is still scrollable. (For example, you can scroll through the content using the arrow keys.) Second, the content in a ScrollViewer is laid out differently. When you use Disabled, you tell the content in the ScrollViewer that it has only as much space as the ScrollViewer itself. On the other hand, if you use Hidden you tell the content that it has an infinite amount of space. That means it can overflow and stretch off into the scrollable region. Ordinarily, you’ll only use Hidden if you plan to allow scrolling by another mechanism (such as the custom scrolling buttons described next). You’ll only use Disabled if you want to temporarily prevent the ScrollViewer from doing anything at all.
The ScrollViewer also supports horizontal scrolling. However, the HorizontalScrollBarVisibility property is Hidden by default. To use horizontal scrolling, you need to change this value to Visible or Auto.
Programmatic Scrolling To scroll through the window in Figure 5-5, you can click the scroll bar with the mouse, you can move over the grid and use a mouse scroll wheel, you can tab through the controls, or you can click somewhere on the blank surface of the grid and use the up and down arrow keys. If this still doesn’t give you the flexibility you crave, you can use the methods of the ScrollViewer class to scroll your content programmatically: • The most obvious are LineUp() and LineDown(), which are equivalent to clicking the arrow buttons on the vertical scroll bar to move up or down once. • You can also use PageUp() and PageDown(), which scroll an entire screenful up or down and are equivalent to clicking the surface of the scroll bar, above or below the scroll bar thumb. • Similar methods allow horizontal scrolling, including LineLeft(), LineRight(), PageLeft(), and PageRight(). • Finally, you can use the ScrollToXxx() methods to go somewhere specific. For vertical scrolling, they include ScrollToEnd() and ScrollToHome(), which take you to the top or bottom of the scrollable content, and ScrollToVerticalOffset(), which takes you to a specific position. There are horizontal versions of the same methods, including ScrollToLeftEnd(), ScrollToRightEnd(), and ScrollToHorizontalOffset().
131
132
CHAPTER 5 ■ CONTENT
Figure 5-6 shows an example where several custom buttons allow you to move through the ScrollViewer. Each button triggers a simple event handler that uses one of the methods in the previous list.
Figure 5-6. Programmatic scrolling
Custom Scrolling The built-in scrolling in the ScrollViewer is quite useful. It allows you to scroll slowly through any content, from a complex vector drawing to a grid of elements. However, one of the most intriguing features of the ScrollViewer is its ability to let its content participate in the scrolling process. Here’s how it works: • You place a scrollable element inside the ScrollViewer. This is any element that implements IScrollInfo. • You tell the ScrollViewer that the content knows how to scroll itself by setting the ScrollViewer.CanContentScroll property to true. • When you interact with the ScrollViewer (by using the scroll bar, the mouse wheel, the scrolling methods, and so on), the ScrollViewer calls the appropriate methods on your element using the IScrollInfo interface. The element then performs its own custom scrolling.
■Note The IScrollInfo defines a set of methods that react to different scrolling actions. For example, it includes many of the scrolling methods exposed by the ScrollViewer, such as LineUp, LineDown(), PageUp(), and PageDown(). It also defines methods that handle the mouse wheel.
Very few elements implement IScrollInfo. One element that does is the StackPanel container. Its implementation of IScrollInfo implements logical scrolling, scrolling that moves from element to element rather than from line to line. If you place a StackPanel in a ScrollViewer and you don’t set the CanContentScroll property, you get the ordinary behavior. Scrolling up and down moves you a few pixels at a time. However, if you set CanContentScroll to true, each time you click down you scroll to the beginning of the next element:
CHAPTER 5 ■ CONTENT
1 2 3 4 You may or may not find that the StackPanel’s logical scrolling system is useful in your application. However, it’s indispensable if you want to create a custom panel with specialized scrolling behavior.
The GroupBox and TabItem: Headered Content Controls One of the classes that derive from ContentControl is HeaderedContentControl. Its role is simple—it represents a container that has both single-element content (as stored in the Content property) and a single-element header (as stored in the Header property). There are three classes that derive from ContentControl: GroupBox, TabItem, and Expander. The GroupBox is the simplest of the three. It’s displayed as a box with rounded corners and a title. Here’s an example (shown in Figure 5-7): One Two Three Save
Figure 5-7. A basic group box Notice that the GroupBox still requires a layout container (such as a StackPanel) to arrange its contents. The GroupBox is often used to group small sets of related controls, such
133
134
CHAPTER 5 ■ CONTENT
as radio buttons. However, the GroupBox has no built-in functionality, so you can use it however you want. (RadioButton objects are grouped by placing them into any panel. A GroupBox is not required, unless you want the rounded, titled border.) The TabItem represents a page in a TabControl. The only significant member that the TabItem class adds is the IsSelected property, which indicates whether the tab is currently being shown in the TabControl. Here’s the markup that’s required to create the simple example that’s shown in Figure 5-8: Setting One Setting Two Setting Three ...
■Tip You can use the TabStripPlacement property to make the tabs appear on the side of the tab control, rather than their normal location at the top.
Figure 5-8. A set of tabs As with the Content property, the Header property can accept any type of object. It displays UIElement-derived classes by rendering them and uses the ToString() method for inline
CHAPTER 5 ■ CONTENT
text and all other objects. That means you can create a group box or a tab with graphical content or arbitrary elements in its title. Here’s an example: Image and Text Tab Title Setting One Setting Two Setting Three Figure 5-9 shows the somewhat garish result.
Figure 5-9. An exotic tab title
The Expander The most exotic headered content control is the Expander. It wraps a region of content that the user can show or hide by clicking a small arrow button. This technique is used frequently in online help and on web pages to allow them to include large amounts of content without overwhelming users with information they don’t want to see.
135
136
CHAPTER 5 ■ CONTENT
Figure 5-10 shows two views of a window with three expanders. In the version on the left, all three expanders are collapsed. In the version on the right, all the regions are expanded. (Of course, users are free to expand or collapse any combination of expanders individually.)
Figure 5-10. Hiding content with expandable regions Using an Expander is extremely simple—you simply need to wrap the content you want to make collapsible inside. Ordinarily, each Expander begins collapsed, but you can change this in your markup (or in your code) by setting the IsExpanded property. Here’s the markup that creates the example shown in Figure 5-10: Hidden Button One Lorem ipsum dolor sit amet, consectetuer adipiscing elit ... Hidden Button Two
CHAPTER 5 ■ CONTENT
You can also choose which direction the expander “expands” in. In Figure 5-10, the standard value (Down) is used, but you can also set the ExpandDirection property to Up, Left, or Right. When the Expander is collapsed, the arrow always points in the direction where it will expand. Life gets a little interesting when using different ExpandDirection values because the effect on the rest of your user interface depends on the type of container. Some containers, such as the WrapPanel, simply bump other elements out of the way. Others, such as Grid, have the option of using proportional or automatic sizing. Figure 5-11 shows an example with a four-cell grid in various degrees of expansion. In each cell is an Expander with a different ExpandDirection. The columns are sized proportionately, which forces the text in the Expander to wrap. (An autosized column would simply stretch to fit the text, making it larger than the window.) The rows are set to automatic sizing, so they expand to fit the extra content.
Figure 5-11. Expanding in different directions
137
138
CHAPTER 5 ■ CONTENT
The Expander is a particularly nice fit in WPF because WPF encourages you to use a flowing layout model that can easily handle content areas that grow or shrink dynamically. If you need to synchronize other controls with an Expander, you can handle the Expanded and Collapsed events. Contrary to what the naming of these events implies, they fire just before the content appears or disappears. This gives you a useful way to implement a lazy load. For example, if the content in an Expander is expensive to create, you might wait until it’s shown to retrieve it. Or perhaps you want to update the content just before it’s shown. Either way, you can react to the Expanded event to perform your work.
■Note If you like the functionality of the Expander but aren’t impressed with the built-in appearance, don’t worry. Using the template system in WPF, you can completely customize the expand and collapse arrows so they match the style of the rest of your application. You’ll learn how in Chapter 15.
Ordinarily, when you expand an Expander it grows to fit its content. This may create a problem if your window isn’t large enough to fit all the content when everything is expanded. There are several strategies for handling this problem: • You can set a minimum size for the window (using MinWidth and MinHeight) to make sure it will fit everything even at its smallest. • You can set the SizeToContent property of the window so that it expands automatically to fit the exact dimensions you need when you open or close an Expander. Ordinarily, SizeToContent is set to Manual, but you can use Width or Height to make it expand or contract in either dimension to accommodate its content. • You can limit the size of the Expander by hard-coding its Height and Width. Unfortunately, this is likely to truncate the content that’s inside if it’s too large. • You can create a scrollable expandable region using the ScrollViewer. For the most part, these techniques are quite straightforward. The only one that requires any further exploration is the combination of an Expander and a ScrollViewer. In order for this approach to work, you need to hard-code the size for the ScrollViewer. Otherwise, it will simply expand to fit its content. Here’s an example: ... It would be nice to have a system in which an Expander could set the size of its content region based on the available space in a window. However, this would present obvious complexities. (For example, how would space be shared between multiple regions when an
CHAPTER 5 ■ CONTENT
Expander expands?) The Grid layout container might seem like a potential solution, but unfortunately it doesn’t integrate well with the Expander. If you try it out you’ll end up with oddly spaced rows that don’t update their heights properly when an Expander is collapsed.
Decorators You’ve now seen several containers that are designed to help you manage other bits of content, including the ScrollViewer, GroupBox, and Expander. That makes this a good point to pause and consider another branch of container-like elements that aren’t content controls. These are decorators, and they’re typically used to add some sort of graphical embellishment around an object. All decorators derive from the System.Windows.Controls.Decorator. Most decorators are designed for use with specific controls. For example, the Button uses a ButtonChrome decorator to get its trademark rounded corner and shaded background, while the ListBox uses the ListBoxChrome decorator. Changing the appearance of these controls involves replacing their decorator with something else, as you’ll see in Chapter 15. There are also two more general decorators that are useful when composing user interfaces: the Border and the Viewbox.
The Border The Border class is pure simplicity. It takes a single piece of nested content (which is often a layout panel) and adds a background or border around it. To master the Border, you need nothing more than the properties listed in Table 5-1. Table 5-1. Properties of the Border Class
Name
Description
Background
Sets a background that appears behind all the content in the border using a Brush object. You can use a solid color or something more exotic.
BorderBrush and BorderThickness
Set the color of the border that appears at the edge of the Border object, using a Brush object, and set the width of the border, respectively. To show a border, you must set both properties.
CornerRadius
Allows you to gracefully round the corners of your border. The greater the CornerRadius, the more dramatic the rounding effect is.
Padding
Adds spacing between the border and the content inside. (By contrast, margin adds spacing outside the border.)
Here’s a straightforward, slightly rounded border around a group of buttons in a StackPanel: One
139
140
CHAPTER 5 ■ CONTENT
Two Three Figure 5-12 shows the result.
Figure 5-12. A basic border Chapter 7 has more details about brushes and the colors you can use to set BorderBrush and Background.
■Note Content controls already have border properties. For example, the Expander controls shown in Figure 5-10 and Figure 5-11 use them to draw a nice outline around the expandable region. (The only exception is the Button control, which doesn’t use its border properties because it relies on the ButtonChrome decorator instead.) The Border element is intended to add a border around elements that don’t have this functionality—namely the layout containers you explored in Chapter 4.
The Viewbox The Viewbox is a more exotic decorator. Its full use won’t become apparent until you learn more about custom drawing in Chapter 13. However, the basic principle behind the Viewbox is easy enough to grasp. Basically, any content you place inside the Viewbox is scaled up or down to fit the bounds of the Viewbox. The Viewbox scaling process is much more dramatic than the stretch alignment settings you learned about in Chapter 4. When you stretch an element, you simply change the space that’s available to that element. This change doesn’t have an effect on most vector content because vector drawings usually use fixed coordinates. For example, consider the button-with-a-shape example that you saw earlier. This shape is placed inside a Grid, and the Grid sizes itself just big enough to fit all the polygons inside. If you enlarge the button, the shape doesn’t change—it’s just centered inside the button (see Figure 5-13). That’s because the size of each polygon is set in absolute coordinates.
CHAPTER 5 ■ CONTENT
Figure 5-13. A resized graphical button The scaling that the Viewbox does is similar to the scaling you see in WPF if you increase the system DPI setting. It changes every onscreen element proportionately, including images, text, lines and shapes, and the borders on common elements such as the button. If you revise the button-with-a-shape example by wrapping the Grid in a Viewbox, you’ll see the resizing behavior that’s shown in Figure 5-14:
Figure 5-14. A resized graphical button that uses a Viewbox
141
142
CHAPTER 5 ■ CONTENT
Even though the polygons in the Grid use hard-coded coordinates, the Viewbox is clever enough to transform these coordinates. It decides how to transform them by comparing the Grid’s desired size—the size it wants to make itself based on the shape content—against the available size. For example, if the Viewbox is twice as large as the Grid’s desired size, the Viewbox scales all its content by a factor of 2.
■Note Usually, you’ll only want to use the Viewbox for vector graphics, not ordinary elements and controls.
By default, the Viewbox performs proportional scaling that preserves the aspect ratio of its contents. That means that even if the shape of the button changes, the shape inside won’t. (Instead, the Viewbox uses the largest scaling factor that fits inside the available space.) However, you can change this behavior using the Viewbox.Stretch property. By default, it’s set to Uniform. Change it to Fill, and the content inside the Viewbox is stretched in both directions to fit the available space exactly, even if it mangles your original drawing. You can also get more control with the StretchDirection property. By default, this property is set to Both, but you can use UpOnly to create content that can grow but won’t shrink beyond its original size and DownOnly to create content that can shrink but not grow.
■Tip If you need more control, such as the ability to set a maximum upper bound and lower bound for the size of your content, consider limiting the size of the Viewbox (or its container) using properties such as MaxHeight, MinHeight, MaxWidth, and MinWidth.
The Last Word As you’ve seen, WPF supports more than one content model. In the previous chapter, you learned about panels, which can wrap multiple elements and apply layout logic. In this chapter you considered content controls, which hold a single element and can range from basics (labels and buttons) to specialized containers that create scrollable and collapsible regions. You also took a quick detour to consider decorators, which allow you to add borders and provide dynamic scaling. WPF still has more in store. In later chapters, you’ll learn about items controls that have yet another content model—they can hold multiple items, each of which is displayed in a specific way (in a list box, a tree, a menu, and so on). But first, in the next chapter you’ll consider the changes in the WPF event system and a new type of property.
CHAPTER
6
■■■
Dependency Properties and Routed Events E
very .NET programmer is familiar with properties and events, which are a core part of .NET’s object abstraction. Few would expect WPF, a user interface technology, to change either of these fundamentals. But surprisingly enough, that’s exactly what WPF does. First, WPF replaces ordinary .NET properties with a higher-level dependency property feature. Dependency properties use more efficient storage and support higher-level features such as change notification and property value inheritance (the ability to propagate default values down the element tree). Dependency properties are also the basis for a number of key WPF features, including animation, data binding, and styles. Fortunately, even though the plumbing has changed, you can read and set dependency properties in code in exactly the same way as traditional .NET properties. The second shift replaces ordinary .NET events with a higher level routed event feature. Routed events are events with more traveling power—they can tunnel down or bubble up the element tree and be processed by event handlers along the way. Routed events allow an event to be handled on one element (such as a label) even though it originates on another (such as an image inside that label). As with dependency properties, routed events can be consumed in the traditional way—by connecting an event handler with the right signature—but you need to understand how they work to unlock all their features. In this chapter, you’ll start by taking a look at dependency properties. You’ll see how they’re defined and what features they support. Then you’ll explore the WPF event system and learn how to fire and handle routed events. Finally, you’ll consider the essential WPF events for dealing with mouse and keyboard actions.
Understanding Dependency Properties Dependency properties are a completely new implementation of properties—one that has a significant amount of added value. You need dependency properties to plug into core WPF features, such as animation, data binding, and styles. Most of the properties that are exposed by WPF elements are dependency properties. In all the examples you’ve seen up to this point, you’ve been using dependency properties without realizing it. That’s because dependency properties are designed to be consumed in the same way as normal properties. 143
144
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
However, dependency properties are not normal properties. It’s comforting to think of a dependency property as a normal property (defined in the typical .NET fashion) with a set of WPF features added on. Conceptually, dependency features behave this way, but that’s not how they’re implemented behind the scenes. The simple reason why is performance. If the designers of WPF simply added extra features on top of the .NET property system, they’d need to create a complex, bulky layer for your code to travel through. Ordinary properties could not support all the features of dependency properties without this extra overhead. Dependency properties are a WPF-specific creation. However, the dependency properties in the WPF libraries are always wrapped by ordinary .NET property procedures. This makes them usable in the normal way, even with code that has no understanding of the WPF dependency property system. It seems odd to think of an older technology wrapping a newer one, but that’s how WPF is able to change a fundamental ingredient such as properties without disrupting the rest of the .NET world.
Defining and Registering a Dependency Property You’ll spend much more time using dependency properties than creating them. However, there are still many reasons that you’ll need to create your own dependency properties. Obviously, they’re a key ingredient if you’re designing a custom WPF element. However, they’re also required in some cases if you want to add data binding, animation, or another WPF feature to a portion of code that wouldn’t otherwise support it. For example, you’ll see your first required use of dependency properties in Chapter 9, when persisting custom information in a pagebased application. Creating a dependency property isn’t difficult, but the syntax takes a little getting used to. It’s thoroughly different than creating an ordinary .NET property. The first step is to define an object that represents your property. This is an instance of the DependencyProperty class. The information about your property needs to be available all the time, and possibly even shared among classes (as is common with WPF elements). For that reason, your DependencyProperty object must be defined as a static field in the associated class. For example, the FrameworkElement class defines a Margin property that all elements share. Unsurprisingly, Margin is a dependency property. That means it’s defined in the FrameworkElement class like this: public class FrameworkElement : UIElement, ... { public static readonly DependencyProperty MarginProperty; ... } By convention, the field that defines a dependency property has the name of the ordinary property, plus the word Property at the end. That way, you can separate the dependency property definition from the name of the actual property. The field is defined with the readonly keyword, which means it can only be set in the static constructor for the FrameworkElement. (WPF also ensures that the DependencyProperty object can’t be changed after it’s been created. All the DependencyProperty members are read-only, and their values must be supplied as constructor arguments when the DependencyProperty object is instantiated.)
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
Defining the DependencyProperty object is just the first step. In order for it to become fully active, you need to register your dependency property with WPF. This detail needs to be completed before any code uses the property, so it must be performed in a static constructor for the associated class. For example, the FrameworkElement class uses this static constructor to initialize the MarginProperty before any instance code runs: static FrameworkElement() { FrameworkPropertyMetadata metadata = new FrameworkPropertyMetadata( new Thickness(), FrameworkPropertyMetadataOptions.AffectsMeasure); MarginProperty = DependencyProperty.Register("Margin", typeof(Thickness), typeof(FrameworkElement), metadata, new ValidateValueCallback(FrameworkElement.IsMarginValid)); ... } There are two steps involved in registering a dependency property. First, you create a FrameworkPropertyMetadata object that indicates what services you want to use with your dependency property (such as support for data binding, animation, and journaling). Next, you register the property by calling the static DependencyProperty.Register() method. At this point, you are responsible for supplying a few key ingredients: • The property name (Margin in this example) • The data type used by the property (the Thickness structure in this example) • The type that owns this property (the FrameworkElement class in this example) • Optionally, a FrameworkPropertyMetadata object with additional property settings • Optionally, a callback that performs validation for the property The first three details are all straightforward. The FrameworkPropertyMetadata object and the validation callback are more interesting. You’ll take a look at these details in the following two sections.
Property Validation The validation callback allows you to enforce the validation that you’d normally add in the set portion of a property procedure. The callback you supply must point to a method that accepts an object parameter and returns a Boolean value. You return true to accept the object as valid, and false to reject it. The validation of the FrameworkElement.Margin property isn’t terribly interesting because it relies on an internal Thickness.IsValid() method. This method makes sure the Thickness object is valid for its current use (representing a margin). For example, it may be possible to construct a perfectly acceptable Thickness object that isn’t acceptable for setting the margin. One example is a Thickness object with negative dimensions. If the supplied Thickness object isn’t valid for a margin, the IsMarginValid property returns false:
145
146
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
private static bool IsMarginValid(object value) { Thickness thickness1 = (Thickness) value; return thickness1.IsValid(true, false, true, false); } There’s one limitation with validation callbacks: they are static methods that don’t have access to the object that’s being validated. All you get is the newly applied value. While that makes them easier to reuse, it also makes it impossible to create a validation routine that takes other properties into account. The classic example is an element with a Maximum and Minimum property. Clearly, it should not be possible to set the Maximum to a value that’s less than the Minimum. However, you can’t enforce this logic with a validation callback because you’ll only have access to one property at a time.
■Note The preferred approach to solve this problem is to use value coercion. Coercion is a step that occurs just before validation, and it allows you to modify a value to make it more acceptable (for example, raising the Maximum so it’s at least equal to the Minimum) or disallow the change altogether. The coercion step is handled through another callback, but this one’s attached to the FrameworkPropertyMetadata object, which is described in the next section.
The Property Wrapper The final step is to wrap your WPF property in traditional .NET property. However, whereas typical property procedures retrieve or set the value of a private field, the property procedures for a WPF property use the GetValue() and SetValue() methods that are defined in the base DependencyObject class. Here’s an example: public Thickness Margin { set { SetValue(MarginProperty, value); } get { return (Thickness)GetValue(MarginProperty); } } When you create the property wrapper, you should include nothing more than a call to SetValue() and a call to GetValue(), as in the previous example. You should not add any extra code to validate values, raise events, and so on. That’s because other features in WPF may bypass the property wrapper and call SetValue() and GetValue() directly. (One example is when a compiled XAML file is parsed at runtime.) Both SetValue() and GetValue() are public.
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
■Note The property wrapper isn’t the right place to validate data or raise an event. However, WPF does provide a place for this code—the trick is to use dependency property callbacks. Validation should be performed through the DependencyProperty.ValidateValueCallback shown previously, while events can be raised from the FrameworkPropertyMetadata.PropertyChangedCallback shown in the next section.
You now have a fully functioning dependency property, which you can set just like any other .NET property using the property wrapper: myElement.Margin = new Thickness(5); There’s one extra detail. Dependency properties follow strict rules of precedence to determine their current value. Even if you don’t set a dependency property directly, it may already have a value—perhaps one that’s applied by a binding, style, or animation, or one that’s inherited through the element tree. (You’ll learn more about these rules of precedence a bit later in the section “How WPF Uses Dependency Properties.”) However, as soon as you set the value directly, it overrides all these other influences. At some point later, you may want to remove your local value setting and let the property value be determined as though you never set it. Obviously, you can’t accomplish this by setting a new value. Instead, you need to use another method that’s inherited from DependencyObject: the ClearValue() method. Here’s how it works: myElement.ClearValue(FrameworkElement.MarginProperty);
Property Metadata Technically, you don’t need to create a FrameworkPropertyMetadata object because there’s an overload of the Dependency.Register() method that doesn’t require one. However, you need the FrameworkPropertyMetadata object if you want to configure any one of a number of dependency property features.
■Note In the Windows Forms platform, the same function is provided using ordinary .NET attributes from several namespaces. Although you’ll still use some attributes with WPF elements (for example, to attach custom type converters), the system is clearer because several important options are grouped into the FrameworkPropertyMetadata class.
Most of these features are configured through simple Boolean flags. (The default value for each Boolean flag is false.) A few are callbacks that point to custom methods that you create to perform a specific task. Table 6-1 lists the available properties.
147
148
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
Table 6-1. Properties of the FrameworkPropertyMetadata Class
Name
Description
AffectsArrange, AffectsMeasure, AffectsParentArrange, and AffectsParentMeasure
If true, the dependency property may affect how adjacent elements (or the parent element) are placed during the measure pass and the arrange pass of a layout operation. For example, the Margin dependency property sets AffectsMeasure to true, signaling that if the margin of an element changes, the layout container needs to repeat the measure step to determine the new placement of elements.
AffectsRender
If true, the dependency property may affect something about the way an element is drawn, requiring that the element be repainted.
BindsTwoWayByDefault
If true, this dependency property will use two-way data binding instead of one-way data binding by default. However, you can specify the binding behavior you want explicitly when you create the binding.
Inherits
If true, the dependency property value propagates through the element tree and can be inherited by nested elements. For example, Font is an inheritable dependency property—if you set it on a higher level element, it’s inherited by nested elements, unless they explicitly override it with their own font settings.
IsAnimationProhibited
If true, the dependency property can’t be used in an animation.
IsNotDataBindable
If true, the dependency property can’t be set with a binding expression.
Journal
If true, this dependency property will be persisted to the journal (the history of visited pages) in a page-based application.
SubPropertiesDoNotAffectRender If true, WPF will not rerender an object if one of its subproperties (the property of a property) changes. DefaultUpdateSourceTrigger
This sets the default value for the Binding.UpdateSourceTrigger property when this property is used in a binding expression. The UpdateSourceTrigger determines when a databound value applies its changes. You can set the UpdateSourceTrigger property manually when you create the binding.
DefaultValue
This sets the default value for the dependency property.
CoerceValueCallback
This provides a callback that attempts to “correct” a property value before it’s validated.
PropertyChangedCallback
This provides a callback that is called when a property value is changed.
Property Coercion It’s important to understand the relationship between the ValidateValueCallback (which you can supply as an argument to the DependencyProperty.Register() method) and the PropertyChangedCallback and CoerceValueCallback (which you can supply as constructor arguments when creating the FrameworkPropertyMetadata object). Here’s how all the pieces come into play: • First, the CoerceValueCallback method has the opportunity to modify the supplied value (usually, to make it consistent with other properties) or return DependencyProperty.UnsetValue, which rejects the change altogether.
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
• Next, the ValidateValueCallback is fired. This method returns true to accept a value as valid, or false to reject it. Unlike the CoerceValueCallback, the ValidateValueCallback does not have access to the actual object on which the property is being set, which means you can’t examine other property values. • Finally, if both these previous stages succeed, the PropertyChangedCallback is triggered. At this point, you can raise a change event if you want to provide notification to other classes. The CoerceValueCallback is the preferred way to deal with interrelated properties. For example, the ScrollBar provides Maximum, Minimum, and Value properties, all of which are inherited from the RangeBase class. When the Maximum is set, it’s coerced so that it can’t be less than the Minimum: private static object CoerceMaximum(DependencyObject d, object value) { RangeBase base1 = (RangeBase)d; if (((double) value) < base1.Minimum) { return base1.Minimum; } return value; } In other words, if the value that’s applied to the Maximum property is less than the Minimum, the Minimum value is used instead to cap the Maximum. Notice that the CoerceValueCallback passes two parameters—the value that’s being applied, and the object to which it’s being applied. When the Value is set, a similar coercion takes place. The Value property is coerced so that it can’t fall outside of the range defined by the Minimum and Maximum, using this code: internal static object ConstrainToRange(DependencyObject d, object value) { double newValue = (double)value; RangeBase base1 = (RangeBase)d; double minimum = base1.Minimum; if (newValue < minimum) { return minimum; } double maximum = base1.Maximum; if (newValue > maximum) { return maximum; } return newValue; }
149
150
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
The Minimum property doesn’t use value coercion at all. Instead, once it has been changed, it triggers a PropertyChangedCallback that forces the Maximum and Value properties to follow along by manually triggering their coercion: private static void OnMinimumChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) { RangeBase base1 = (RangeBase)d; ... base1.CoerceValue(RangeBase.MaximumProperty); base1.CoerceValue(RangeBase.ValueProperty); } Similarly, once the Maximum has been set and coerced, it manually coerces the Value property to fit: private static void OnMaximumChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) { RangeBase base1 = (RangeBase)d; ... base1.CoerceValue(RangeBase.ValueProperty); base1.OnMaximumChanged((double) e.OldValue, (double) e.NewValue); } The end result is that if you set conflicting values, the Minimum takes precedence, the Maximum gets its say next (and may possibly be coerced by the Minimum), and then the Value is applied (and may be coerced by both the Maximum and Minimum). The goal of this somewhat confusing sequence of steps is to ensure that the ScrollBar properties can be set in various orders without causing an error. This is an important consideration for initialization, such as when a window is being created for a XAML document. All WPF controls guarantee that their properties can be set in any order, without causing any change in behavior. A careful review of the previous code calls this goal into question. For example, consider this code: ScrollBar bar = new ScrollBar(); bar.Value = 100; bar.Minimum = 1; bar.Maximum = 200; When the ScrollBar is first created, Value is 0, Minimum is 0, and Maximum is 1. After the second line of code, the Value property is coerced to 1 (because initially the Maximum property is set to the default value 1). But something remarkable happens when you reach the fourth line of code. When the Maximum property is changed, it triggers coercion on both the Minimum and Value properties. This coercion acts on the values you specified originally. In other words, the local value of 100 is still stored by the WPF dependency property system, and now that it’s an acceptable value, it can be applied to the Value property. Thus, after this single line of code executes, two properties have changed. Here’s a closer look at what’s happening:
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
ScrollBar bar = new ScrollBar(); bar.Value = 100; // (Right now bar.Value returns 1.) bar.Minimum = 1; // (bar.Value still returns 1.) bar.Maximum = 200; // (Now now bar.Value returns 100.) This behavior persists no matter when you set the Maximum property. For example, if you set a Value of 100 when the window loads, and set the Maximum property later when the user clicks a button, the Value property is still restored to its rightful value of 100 at that point. (The only way to prevent this from taking place is to set a different value or remove the local value that you’ve applied using the ClearValue() method that all elements inherit from DependencyObject). This behavior is due to WPF’s property resolution system, which stores the exact local value you’ve set internally but evaluates what the property should be (using coercion and a few other considerations) when you read the property. More information about this system is in the section “How WPF Uses Dependency Properties” later in this chapter.
■Note Long-time Windows Forms programmers may remember the ISupportInitialize interface, which was used to solve similar problems in property initialization by wrapping a series of property changes into a batch process. Although you can use ISupportInitialize with WPF (and the XAML parser respects it), few of the WPF elements use this technique. Instead, it’s encouraged to resolve these problems using value coercion. There are a number of reasons that coercion is preferred. For example, coercion solves other problems that can occur when an invalid value is applied through a data binding or animation, unlike the ISupportInitialize interface.
Shared Dependency Properties Some classes share the same dependency property, even though they have separate class hierarchies. For example, both TextBlock.FontFamily and Control.FontFamily point to the same static dependency property, which is actually defined in the TextElement class and TextElement.FontFamilyProperty. The static constructor of TextElement registers the property, but the static constructors of TextBlock and Control simply reuse it by calling the DependencyProperty.AddOwner() method: TextBlock.FontFamilyProperty = TextElement.FontFmamilyProperty.AddOwner(typeof(TextBlock)); You can use the same technique when you create your own custom classes (assuming the property is not already provided in the class you’re inheriting from, in which case you get it for free). You can also use an overload of the AddOwner() method that allows you to supply a validation callback and a new FrameworkPropertyMetadata that will only apply to this new use of the dependency property.
151
152
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
Reusing dependency properties can lead to some strange side effects in WPF, most notably with styles. For example, if you use a style to set the TextBlock.FontFamily property automatically, your style will also affect the Control.FontFamily property because behind the scenes both classes use the same dependency property. You’ll see this phenomenon in action in Chapter 12.
Attached Dependency Properties Chapter 2 introduced a special type of dependency property called an attached property. An attached property is a dependency property, and it’s managed by the WPF property system. The difference is that an attached property applies to a class other than the one where it’s defined. The most common example of attached properties is found in the layout containers described in Chapter 4. For example, the Grid class defines the attached properties Row and Column, which you set on the contained elements to indicate where they should be positioned. Similarly, the DockPanel defines the attached property Dock, and the Canvas defines the attached properties Left, Right, Top, and Bottom. To define an attached property, you use the RegisterAttached() method instead of Register(). Here’s an example that registers the Grid.Row property: FrameworkPropertyMetadata metadata = new FrameworkPropertyMetadata( 0, new PropertyChangedCallback(Grid.OnCellAttachedPropertyChanged)); Grid.RowProperty = DependencyProperty.RegisterAttached("Row", typeof(int), typeof(Grid), metadata, new ValidateValueCallback(Grid.IsIntValueNotNegative)); As with an ordinary dependency property, you can supply a FrameworkPropertyMetadata object and a ValidateValueCallback. When creating an attached property, you don’t define the .NET property wrapper. That’s because attached properties can be set on any dependency object. For example, the Grid.Row property may be set on a Grid object (if you have one Grid nested inside another) or on some other element. In fact, the Grid.Row property can be set on an element even if that element isn’t in a Grid—and even if there isn’t a single Grid object in your element tree. Instead of using a .NET property wrapper, attached properties require a pair of static methods that can be called to set and get the property value. These methods use the familiar SetValue() and GetValue() methods (inherited from the DependencyObject class). The static methods should be named SetPropertyName() and GetPropertyName(). Here are the static methods that implement the Grid.Row attached property: public static int GetRow(UIElement element) { if (element == null) { throw new ArgumentNullException("element"); } return (int)element.GetValue(Grid.RowProperty); } public static void SetRow(UIElement element, int value)
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
{ if (element == null) { throw new ArgumentNullException("element"); } element.SetValue(Grid.RowProperty, value); } Here’s an example that positions an element in the first row of a Grid using code: Grid.SetRow(txtElement, 0); Alternatively, you can call the SetValue() or GetValue() method directly and bypass the static methods: txtElement.SetValue(Grid.RowProperty, 0); The SetValue() method also provides one brain-twisting oddity. Although XAML doesn’t allow it, you can use an overloaded version of the SetValue() method in code to attach a value for any dependency property, even if that property isn’t defined as an attached property. For example, the following code is perfectly legitimate: ComboBox comboBox = new ComboBox(); ... comboBox.SetValue(PasswordBox.PasswordCharProperty, "*"); Here, a value for the PasswordBox.PasswordChar property is set for a ComboBox object, even though PasswordBox.PasswordCharProperty is registered as an ordinary dependency property, not an attached property. This action won’t change the way the ComboBox works— after all, the code inside the ComboBox won’t look for the value of a property that it doesn’t know exists—but you could act upon the PasswordChar value in your own code. Although rarely used, this quirk provides some more insight into the way the WPF property system works, and it demonstrates its remarkable extensibility. It also shows that even though attached properties are registered with a different method than normal dependency properties, in the eyes of WPF there’s no real distinction. The only difference is what the XAML parser allows. Unless you register your property as an attached property, you won’t be able to set it in on other elements in your markup.
How WPF Uses Dependency Properties As you’ll discover throughout this book, dependency properties are required for a range of WPF features. However, all of these features work through two key behaviors that every dependency property supports—change notification and dynamic value resolution. As you’ve already seen, when you change the value of a dependency property, a callback is triggered. This callback is part of the low-level plumbing of WPF, and it takes care of updating data bindings and firing triggers. Contrary to what you might expect, dependency properties do not automatically fire events to let you know when a property value changes. Instead, they trigger a protected method named OnPropertyChangedCallback(). This method passes the information along to two WPF services (data binding and triggers) and calls the PropertyChangedCallback, if one is defined.
153
154
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
In other words, if you want to perform an action when a property changes, you have two choices—you can create a binding that uses the property value (Chapter 15), or you can write a trigger that automatically changes another property or starts an animation (Chapter 12). However, dependency properties don’t give you a general-purpose way to fire off some code to respond to a property change.
■Note If you’re dealing with a control that you’ve created, you can use the property callback mechanism to react to property changes and even raise an event. Many common controls use this technique for properties that correspond to user-supplied information. For example, the TextBox provides a TextChanged event and the ScrollBar provides a ValueChanged event. A control can implement functionality like this using the PropertyChangedCallback, but this functionality isn’t exposed from dependency properties in a general way for performance reasons.
The second feature that’s key to the way dependency properties work is dynamic value resolution. This means when you retrieve the value from a dependency property, WPF takes several factors into consideration. You’ve already seen this at work in the ScrollBar example, where the Value property depends on both the value applied locally by code and the CoerceValueCallback. This behavior gives dependency properties their name—in essence, a dependency property depends on multiple property providers, each with its own level of precedence. When you retrieve a value from a property value, the WPF property system goes through a series of steps to arrive at the final value. First, it determines the base value for the property by considering the following factors, arranged from lowest to highest precedence: 1. The default value (as set by the FrameworkPropertyMetadata object) 2. The inherited value (if the FrameworkPropertyMetadata.Inherits flag is set and a value has been applied to an element somewhere up the containment hierarchy) 3. The value from a theme style (as discussed in Chapter 15) 4. The value from a project style (as discussed in Chapter 12) 5. The local value (in other words, a value you’ve set directly on this object using code or XAML) As this list shows, you override the entire hierarchy by applying a value directly. If you don’t, the value is determined by the next applicable item up on the list.
■Note One of the advantages of this system is that it’s very economical. If the value of a property has not been set locally, WPF will retrieve its value from a style, another element, or the default. In this case, no memory is required to store the value. You can quickly see the savings if you add a few buttons to a form. Each button has dozens of properties which, if they are set through one of these mechanisms, use no memory at all.
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
WPF follows the previous list to determine the base value of a dependency property. However, the base value is not necessarily the final value that you’ll retrieve from a property. That’s because WPF considers several other providers that can change a property’s value. Here’s the five-step process WPF follows to determine a property value: 1. Determine the base value (as described previously). 2. If the property is set using an expression, evaluate that expression. Currently, WPF supports two types of expression: resources (Chapter 11) and data binding (Chapter 15). 3. If this property is the target of animation, apply that animation. 4. Run the CoerceValueCallback to “correct” the value. 5. Run the PropertyChangedCallback to disallow invalid data. Essentially, dependency properties are hardwired into a small set of WPF services. If it weren’t for this infrastructure, these features would add unnecessary complexity and significant overhead.
■Tip In future versions of WPF, the dependency property pipeline could be extended to include additional services. When you design custom elements (a topic covered in Chapter 24), you’ll probably use dependency properties for most (if not all) of their public properties.
Understanding Routed Events Every .NET developer is familiar with the idea of events—messages that are sent by an object (such as a WPF element) to notify your code when something significant occurs. WPF enhances the .NET event model with a new concept of event routing. Event routing allows an event to originate in one element but be raised by another one. For example, event routing allows a click that begins in a toolbar button to rise up to the toolbar and then to the containing window before it’s handled by your code. Event routing gives you the flexibility to write tight, well-organized code that handles events in the most convenient place. It’s also a necessity for working with the WPF content model, which allows you to build simple elements (such as a button) out of dozens of distinct ingredients, each of which has its own independent set of events.
Defining and Registering a Dependency Property The WPF event model is quite similar to the WPF property model. As with dependency properties, routed events are represented by read-only static fields, registered in a static constructor, and wrapped by a standard .NET event definition. For example, the WPF Button class provides the familiar Click event, which is inherited from the abstract ButtonBase class. Here’s how the event is defined and registered: public abstract class ButtonBase : ContentControl, ... {
155
156
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
// The event definition. public static readonly RoutedEvent ClickEvent; // The event registration. static ButtonBase() { ButtonBase.ClickEvent = EventManager.RegisterRoutedEvent( "Click", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(ButtonBase)); ... } // The traditional event wrapper. public event RoutedEventHandler Click { add { base.AddHandler(ButtonBase.ClickEvent, value); } remove { base.RemoveHandler(ButtonBase.ClickEvent, value); } } ... } While dependency properties are registered with the DependencyProperty.Register() method, routed events are registered with the EventManager.RegisterRoutedEvent() method. When registering an event, you need to specify the name of the event, the type of routine (more on that later), the delegate that defines the syntax of the event handler (in this example, RoutedEventHandler), and the class that owns the event (in this example, ButtonBase). Usually, routed events are wrapped by ordinary .NET events to make them accessible to all .NET languages. The event wrapper adds and removes registered callers using the AddHandler() and RemoveHandler() methods, both of which are defined in the base FrameworkElement class and inherited by every WPF element. Of course, like any event, the defining class needs to raise it at some point. Exactly where this takes place is an implementation detail. However, the important detail is that your event is not raised through the traditional .NET event wrapper. Instead, you use the RaiseEvent() method that every element inherits from the FrameworkElement class. Here’s the appropriate code from deep inside the ButtonBase class: RoutedEventArgs args1 = new RoutedEventArgs(ButtonBase.ClickEvent, this); base.RaiseEvent(args1); The RaiseEvent() method takes care of firing the event to every caller that’s been registered with the AddHandler() method. Because AddHandler() is public, callers have a
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
choice—they can register themselves directly by calling AddHandler(), or they can use the event wrapper. (The following section demonstrates both approaches.) Either way, they’ll be notified when the RaiseEvent() method is invoked. As with dependency properties, the definition of a routed event can be shared between classes. For example, two base classes use the MouseUp event: UIElement (which is the starting point for ordinary WPF elements) and ContentElement (which is the starting point for content elements, which are individual bits of content that can be placed in a flow document). The MouseUp event is defined by the System.Windows.Input.Mouse class. The UIElement and ContentElement classes simply reuse it with the RoutedEvent.AddOwner() method: UIElement.MouseUpEvent = Mouse.MouseUpEvent.AddOwner(typeof(UIElement)); All WPF events use the familiar .NET convention for event signatures. That first parameter of every event handler provides a reference to the object that fired the event (the sender). The second parameter is an EventArgs object that bundles together any additional details that might be important. For example, the MouseUp event provides a MouseEventArgs object that indicates what mouse buttons were pressed when the event occurred: private void img_MouseUp(object sender, MouseButtonEventArgs e) { } In Windows Forms applications, it was customary for many events to use the base EventArgs class if they didn’t need to pass along any extra information. However, the situation is different in WPF applications due to their support for the routed event model. In WPF, if an event doesn’t need to send any additional details, it uses the RoutedEventArgs class, which includes some details about how the event was routed. If the event does need to transmit extra information, it uses a more specialized RoutedEventArgs-derived object (such as MouseButtonEventArgs in the previous example). Because every WPF event argument class derives from RoutedEventArgs, every WPF event handler has access to information about event routing.
Attaching an Event Handler As you learned in Chapter 2, there are several ways to attach an event handler. The most common approach is to add an attribute to your XAML markup. This attribute is named after the event you want to handle, and its value is the name of the event handler method. Here’s an example that uses this syntax to connect the MouseUp event of the Image to an event handler named img_MouseUp: Although it’s not required, it’s a common convention to name event handler methods in the form ElementName_EventName. If the element doesn’t have a defined name (presumably because you don’t need to interact with it in any other place in your code), consider using the name it would have: OK
157
158
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
■Tip It may be tempting to attach an event to a high-level method that performs a task, but you’ll have more flexibility if you keep an extra layer of event handling code. For example, when you click a button named cmdUpdate, it shouldn’t trigger a method named UpdateDatabase() directly. Instead, it should call an event handler such as cmdUpdate_Click(), which can then call the UpdateDatabase() method that does the real work. This pattern gives you the flexibility to change where your database code is located, replace the update button with a different control, and wire several controls to the same process, all without limiting your ability to change the user interface later on. If you want a simpler way to deal with actions that can be triggered from several different places in a user interface (toolbar buttons, menu commands, and so on), you’ll want to add the WPF command feature that’s described in Chapter 10.
You can also connect an event with delegates and code. Here’s the code equivalent of the XAML markup shown previously: img.MouseUp += new MouseButtonEventHandler(img_MouseUp); This code creates a delegate object that has the right signature for the event (in this case, an instance of the MouseButtonEventHandler delegate) and points that delegate to the img_MouseUp() method. It then adds the delegate to the list of registered event handlers for the img.MouseUp event. C# also allows a more streamlined syntax that creates the appropriate delegate object implicitly: img.MouseUp += img_MouseUp; The code approach is useful if you need to dynamically create a control and attach an event handler at some point during the lifetime of your window. By comparison, the events you hook up in XAML are always attached when the window object is first instantiated. The code approach also allows you to keep your XAML simpler and more streamlined, which is perfect if you plan to share it with nonprogrammers, such as a design artist. The drawback is a significant amount of boilerplate code that will clutter up your code files. The previous code approach relies on the event wrapper, which calls the AddHandler() method, as shown in the previous section. You can also connect an event directly by calling AddHandler() yourself. Here’s an example: img.AddHandler(Image.MouseUpEvent, new MouseButtonEventHandler(img_MouseUp)); When you use this approach, you always need to create the appropriate delegate type (such as MouseButtonEventHandler). You can create the delegate object implicitly, as you can when hooking up an event through the property wrapper. That’s because the AddHandler() method supports all WPF events and it doesn’t know the delegate type that you want to use. Some developers prefer to use the name of the class where the event is defined, rather than the name of the class that is firing the event. Here’s the equivalent syntax that makes it clear that the MouseUpEvent is defined in UIElement: img.AddHandler(UIElement.MouseUpEvent, new MouseButtonEventHandler(img_MouseUp));
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
■Note Which approach you use is largely a matter of taste. However, the drawback to this second approach is that it doesn’t make it obvious that the Image class provides a MouseUpEvent. It’s possible to confuse this code and assume it’s attaching an event handler that’s meant to deal with the MouseUpEvent in a nested element. You’ll learn more about this technique in the section “Attached Events” later in this chapter.
If you want to detach an event handler, code is your only option. You can use the -= operator, as shown here: img.MouseUp -= img_MouseUp; Or you can use the RemoveHandler() helper method: img.RemoveHandler(Image.MouseUpEvent, new MouseButtonEventHandler(img_MouseUp)); It is technically possible to connect the same event handler to the same event more than once. This is usually the result of a coding mistake. (In this case, the event handler will be triggered multiple times.) If you attempt to remove an event handler that’s been connected twice, the event will still trigger the event handler, but just once.
Event Routing As you learned in the previous chapter, many controls in WPF are content controls, and content controls can hold any type and amount of nested content. For example, you can build a graphical button out of shapes, create a label that mixes text and pictures, or put content in a specialized container to get a scrollable or collapsible display. You can even repeat this nesting process to go as many layers deep as you want. This ability for arbitrary nesting raises an interesting question. For example, imagine you have a label like this one, which contains a StackPanel that brings together two blocks of text and an image: Image and text label Courtesy of the StackPanel As you already know, every ingredient you place in a WPF window derives from UIElement at some point, including the Label, StackPanel, TextBlock, and Image. UIElement defines some core events. For example, every class that derives from UIElement provides a MouseDown and MouseUp event.
159
160
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
But consider what happens when you click the image part of the fancy label shown here. Clearly, it makes sense for the Image.MouseDown and Image.MouseUp events to fire. But what if you want to treat all label clicks in the same way? In this case, it shouldn’t matter whether the user clicks the image, some of the text, or part of the blank space inside the label border. In every case, you’d like to respond with the same code. Clearly, you could wire up the same event handler to the MouseDown or MouseUp event of each element, but that would result in a significant amount of clutter and it would make your markup more difficult to maintain. WPF provides a better solution with its routed event model. Routed events actually come in the following three flavors: • Direct events are like ordinary .NET events. They originate in one element and don’t pass to any other. For example, MouseEnter (which fires when the mouse pointer moves over an element) is a direct event. • Bubbling events are events that travel up the containment hierarchy. For example, MouseDown is a bubbling event. It’s raised first by the element that is clicked. Next, it’s raised by that element’s parent, and then by that element’s parent, and so on, until WPF reaches the top of the element tree. • Tunneling events are events that travel down the containment hierarchy. They give you the chance to preview (and possibly stop) an event before it reaches the appropriate control. For example, PreviewKeyDown allows you to intercept a key press, first at the window level, and then in increasingly more specific containers until you reach the element that had focus when the key was pressed. When you register a routed event using the EventManager.RegisterEvent() method, you pass a value from the RoutingStrategy enumeration that indicates the event behavior you want to use for your event. Because MouseUp and MouseDown are bubbling events, you can now determine what happens in the fancy label example. When the happy face is clicked, the MouseDown event fires in this order: 1. Image.MouseDown 2. StackPanel.MouseDown 3. Label.MouseDown After the MouseDown event is raised for the label, it’s passed on to the next control (which in this case is the Grid that lays out the containing window), and then to its parent (the window). The window is the top level of the containment hierarchy and the final stop in the event bubbling sequence. It’s your last chance to handle a bubbling event such as MouseDown. If the user releases the mouse button, the MouseUp event fires in the same sequence.
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
■Note In Chapter 9, you’ll learn how to create a page-based WPF application. In this situation, the toplevel container isn’t a window, but an instance of the Page class.
You aren’t limited to handling a bubbling event in one place. In fact, there’s no reason why you can’t handle the MouseDown or MouseUp event at every level. But usually you’ll choose the most appropriate level for the task at hand.
The RoutedEventArgs Class When you handle a bubbling event, the sender parameter provides a reference to the last link in the chain. For example, if an event bubbles up from an image to a label before you handle it, the sender parameter references the label object. In some cases, you’ll want to determine where the event originally took place. You can get that information and other details from the properties of the RoutedEventArgs class (which are listed in Table 6-2). Because all WPF event argument classes inherit from RoutedEventArgs, these properties are available in any event handler. Table 6-2. Properties of RoutedEventArgs Class
Name
Description
Source
Indicates what object raised the event. In the case of a keyboard event, this is the control that had focus when the event occurred (for example, when the key was pressed). In the case of a mouse event, this is the topmost element under the mouse pointer when the event occurred (for example, when a mouse button was clicked).
OriginalSource
Indicates what object originally raised the event. Usually, the OriginalSource is the same as the source. However, in some cases the OriginalSource goes deeper in the object tree to get a behind-the-scenes element that’s part of a higher-level element. For example, if you click close to the border of a window, you’ll get a Window object for the event source, but a Border object for the original source. That’s because a Window is composed out of individual, smaller components. To take a closer look at this composition model (and learn how to change it), head to Chapter 15, which discusses control templates.
RoutedEvent
Provides the RoutedEvent object for the event triggered by your event handler (such as the static UIElement.MouseUpEvent object). This information is useful if you’re handling different events with the same event handler.
Handled
Allows you to halt the event bubbling or tunneling process. When a control sets the Handled property to true, the event doesn’t travel any farther and isn’t raised for any other elements. (As you’ll see in the section “Handling a Suppressed Event,” there is one way around this limitation.)
161
162
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
Bubbling Events Figure 6-1 shows a simple window that demonstrates event bubbling. When you click a part of the label, the event sequence is shown in a list box. Figure 6-1 shows the appearance of this window immediately after you click the image in the label. The MouseUp event travels through five levels, ending up at the custom BubbledLabelClick form.
Figure 6-1. A bubbled image click To create this test form, the image and every element above it in the element hierarchy are wired up to the same event handler—a method named SomethingClicked(). Here’s the XAML that does it:
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
Image and text label Courtesy of the StackPanel Handle first event Clear List The SomethingClicked() method simply examines the properties of the RoutedEventArgs object and adds a message to the list box: protected int eventCounter = 0; private void SomethingClicked(object sender, RoutedEventArgs e) { eventCounter++; string message = "#" + eventCounter.ToString() + ":\r\n" + " Sender: " + sender.ToString() + "\r\n" + " Source: " + e.Source + "\r\n" + " Original Source: " + e.OriginalSource; lstMessages.Items.Add(message); e.Handled = (bool)chkHandle.IsChecked; }
■Note Technically, the MouseUp event provides a MouseButtonEventArgs object with additional information about the mouse state at the time of the event. However, the MouseButtonEventArgs object derives from MouseEventArgs, which in turn derives from RoutedEventArgs. As a result, it’s possible to use it when declaring the event handler (as shown here) if you don’t need additional information about the mouse.
163
164
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
There’s one other detail in this example. If you’ve checked the chkHandle check box, the SomethingClicked() method sets the RoutedEventArgs.Handled property to true, which stops the event bubbling sequence the first time an event occurs. As a result, you’ll only see the first event appear in the list, as shown in Figure 6-2.
■Note There’s an extra cast required here because the CheckBox.IsChecked property is a nullable Boolean value (a bool? rather than a bool). The null value represents an indeterminate state for the check box, which means it’s neither checked nor unchecked. This feature isn’t used in this example, so a simple cast solves the problem.
Figure 6-2. Marking an event as handled Because the SomethingClicked() method handles the MouseUp event that’s fired by the Window, you’ll be able to intercept clicks on the list box and the blank window surface. However, the MouseUp event doesn’t fire when you click the Clear button (which removes all the list box entries). That’s because the button includes an interesting bit of code that suppresses the MouseUp event and raises a higher-level Click event. At the same time, the Handled flag is set to true, which prevents the MouseUp event from going any further.
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
■Tip Unlike Windows Forms controls, most WPF elements don’t expose a Click event. Instead they include the more straightforward MouseDown and MouseUp events. Click is reserved for button-based controls.
Handling a Suppressed Event Interestingly, there is a way to receive events that are marked as handled. Instead of attaching the event handler through XAML, you must use the AddHandler() method described earlier. The AddHandler() method provides an overload that accepts a Boolean value for its third parameter. Set this to true, and you’ll receive the event even if the Handled flag has been set: cmdClear.AddHander(UIElement.MouseUpEvent, new MouseButtonEventHandler(cmdClear_MouseUp), true); This is rarely a good design decision. The button is designed to suppress the MouseUp event for a reason: to prevent possible confusion. After all, it’s a common Windows convention that buttons can be “clicked” with the keyboard in several ways. If you make the mistake of handling the MouseUp event in a Button instead of the Click event, your code will only respond to mouse clicks, not the equivalent keyboard actions.
Attached Events The fancy label example is a fairly straightforward example of event bubbling because all the elements support the MouseUp event. However, many controls have their own more specialized events. The button is one example—it adds a Click event that isn’t defined by any base class. This introduces an interesting dilemma. Imagine you wrap a stack of buttons in a StackPanel. You want to handle all the button clicks in one event handler. The crude approach is to attach the Click event of each button to the same event handler. But the Click event supports event bubbling, which gives you a better option. You can handle all the button clicks by handling the Click event at a higher level (such as the containing StackPanel). Unfortunately, this apparently obvious code doesn’t work: Command 1 Command 2 Command 3 ... The problem is that the StackPanel doesn’t include a Click event, so this is interpreted by the XAML parser as an error. The solution is to use a different attached-event syntax in the form ClassName.EventName. Here’s the corrected example: Command 1 Command 2 Command 3 ...
165
166
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
Now your event handler receives the click for all contained buttons.
■Note The Click event is actually defined in the ButtonBase class and inherited by the Button class. If you attach an event handler to ButtonBase.Click, that event handler will be used when any ButtonBase-derived control is clicked (including the Button, RadioButton, and CheckBox classes). If you attach an event handler to Button.Click, it’s only used for Button objects.
You can wire up an attached event in code, but you need to use the AddHandler() method rather than the += operator syntax. Here’s an example (which assumes the StackPanel has been given the name pnlButtons): pnlButtons.AddHandler(Button.Click, new RoutedEventHandler(DoSomething)); In the DoSomething() event handler you have several options for determining which button fired the event. You can compare its text (which will cause problems for localization) or its name (which is fragile because you won’t catch mistyped names when you build the application). The best approach is to make sure each button has a Name property set in XAML, so that you can access the corresponding object through a field in your window class and compare that reference with the event sender. Here’s an example: private void DoSomething(object sender, RoutedEventArgs e) { if (sender == cmd1) { ... } else if (sender == cmd2) { ... } else if (sender == cmd3) { ... } } Another option is to simply send a piece of information along with the button that you can use in your code. For example, you could set the Tag property of each button, as shown here: Command 1 Command 2 Command 3 ... You can then access the Tag property in your code: private void DoSomething(object sender, RoutedEventArgs e) { object tag = ((FrameworkElement)sender).Tag; MessageBox.Show((string)tag); }
CHAPTER 6 ■ DEPENDENCY PROPERTIES AND ROUTED EVENTS
Tunneling Events Tunneling events work the same as bubbling events, but in the opposit